mirror of
https://github.com/diegosouzapw/OmniRoute.git
synced 2026-07-26 09:52:11 +03:00
feat: OmniRoute v1.0.0 — Intelligent AI Gateway & Universal LLM Proxy
OmniRoute is an intelligent API gateway that unifies 20+ AI providers behind a single OpenAI-compatible endpoint. Features include intelligent routing with 6 strategies, multi-format translation (OpenAI/Claude/Gemini/Responses API), circuit breakers, semantic caching, combo fallback chains, real-time health monitoring, and a full dashboard with provider management, analytics, and CLI tool integration. Key highlights: - 20+ providers (Claude Code, Codex, Gemini CLI, GitHub Copilot, iFlow, Qwen, Kiro, etc.) - 6 routing strategies (Fill First, Round Robin, P2C, Random, Least Used, Cost Optimized) - Export/Import database backup with full archive support - Translator Playground with 4 modes (Playground, Chat Tester, Test Bench, Live Monitor) - 100% TypeScript across src/ and open-sse/ - Docker support with multi-stage builds - Comprehensive documentation and 9 dashboard screenshots
This commit is contained in:
diegosouzapw
54
.agent/workflows/git-workflow.md
Normal file
54
.agent/workflows/git-workflow.md
Normal file
@@ -0,0 +1,54 @@
|
||||
---
|
||||
description: Git workflow — NEVER commit directly to main. Always use feature branches.
|
||||
---
|
||||
|
||||
# Git Workflow
|
||||
|
||||
## ⚠️ CRITICAL RULE: NEVER commit directly to `main`
|
||||
|
||||
## Steps
|
||||
|
||||
1. **Before starting any work**, create a feature branch from `main`:
|
||||
|
||||
```bash
|
||||
git checkout main && git pull origin main
|
||||
git checkout -b feature/<feature-name>
|
||||
```
|
||||
|
||||
2. **During development**, commit to the feature branch:
|
||||
|
||||
```bash
|
||||
git add -A && git commit -m "<type>(<scope>): <description>"
|
||||
```
|
||||
|
||||
3. **Before pushing**, verify the build passes:
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
4. **When the feature is complete and verified**, push the branch and STOP:
|
||||
|
||||
```bash
|
||||
git push origin feature/<feature-name>
|
||||
```
|
||||
|
||||
5. **DO NOT** create a PR, merge, or push to `main`. Let the user handle that.
|
||||
|
||||
## Branch naming convention
|
||||
|
||||
- `feature/<name>` — new features
|
||||
- `fix/<name>` — bugfixes
|
||||
- `refactor/<name>` — refactoring
|
||||
- `docker/<name>` — Docker / infrastructure changes
|
||||
- `style/<name>` — UI / CSS changes
|
||||
|
||||
## Commit types
|
||||
|
||||
- `feat` — new feature
|
||||
- `fix` — bugfix
|
||||
- `refactor` — code refactoring
|
||||
- `style` — UI / CSS changes
|
||||
- `docker` — Docker / infrastructure
|
||||
- `docs` — documentation
|
||||
- `chore` — maintenance
|
||||
32
.dockerignore
Normal file
32
.dockerignore
Normal file
@@ -0,0 +1,32 @@
|
||||
# VCS
|
||||
.git
|
||||
**/.git
|
||||
|
||||
# Editor
|
||||
.vscode
|
||||
**/.vscode
|
||||
|
||||
# Dependencies and build output
|
||||
node_modules
|
||||
.next
|
||||
out
|
||||
build
|
||||
dist
|
||||
coverage
|
||||
|
||||
# Runtime data and logs
|
||||
data
|
||||
logs
|
||||
|
||||
# Local env files (inject at runtime via --env-file or -e)
|
||||
.env
|
||||
.env.local
|
||||
.env.development.local
|
||||
.env.test.local
|
||||
.env.production.local
|
||||
|
||||
# Debug logs
|
||||
npm-debug.log*
|
||||
yarn-debug.log*
|
||||
yarn-error.log*
|
||||
.pnpm-debug.log*
|
||||
120
.env.example
Normal file
120
.env.example
Normal file
@@ -0,0 +1,120 @@
|
||||
# OmniRoute environment contract
|
||||
# This file reflects actual runtime usage in the current codebase.
|
||||
|
||||
# ═══════════════════════════════════════════════════
|
||||
# REQUIRED SECRETS — Generate strong values!
|
||||
# ═══════════════════════════════════════════════════
|
||||
# Generate with: openssl rand -base64 48
|
||||
JWT_SECRET=
|
||||
# Generate with: openssl rand -hex 32
|
||||
API_KEY_SECRET=
|
||||
|
||||
# Initial admin password — CHANGE THIS before first use!
|
||||
INITIAL_PASSWORD=CHANGEME
|
||||
DATA_DIR=/var/lib/omniroute
|
||||
|
||||
# Storage (SQLite)
|
||||
STORAGE_DRIVER=sqlite
|
||||
# Generate with: openssl rand -hex 32
|
||||
STORAGE_ENCRYPTION_KEY=
|
||||
STORAGE_ENCRYPTION_KEY_VERSION=v1
|
||||
LOG_RETENTION_DAYS=90
|
||||
SQLITE_MAX_SIZE_MB=2048
|
||||
SQLITE_CLEAN_LEGACY_FILES=true
|
||||
|
||||
# Recommended runtime variables
|
||||
PORT=20128
|
||||
NODE_ENV=production
|
||||
INSTANCE_NAME=omniroute
|
||||
|
||||
# Recommended security and ops variables
|
||||
MACHINE_ID_SALT=endpoint-proxy-salt
|
||||
ENABLE_REQUEST_LOGS=false
|
||||
AUTH_COOKIE_SECURE=false
|
||||
REQUIRE_API_KEY=false
|
||||
|
||||
# Input Sanitizer (FASE-01 — prompt injection & PII protection)
|
||||
# INPUT_SANITIZER_ENABLED=true
|
||||
# INPUT_SANITIZER_MODE=warn # warn | block | redact
|
||||
# PII_REDACTION_ENABLED=false
|
||||
|
||||
# Cloud sync variables
|
||||
# Must point to this running instance so internal sync jobs can call /api/sync/cloud.
|
||||
# Server-side preferred variables:
|
||||
BASE_URL=http://localhost:20128
|
||||
CLOUD_URL=
|
||||
# Backward-compatible/public variables:
|
||||
NEXT_PUBLIC_BASE_URL=http://localhost:20128
|
||||
NEXT_PUBLIC_CLOUD_URL=
|
||||
|
||||
# Optional outbound proxy variables for upstream provider calls
|
||||
# Lowercase variants are also supported: http_proxy, https_proxy, all_proxy, no_proxy
|
||||
# SOCKS5 proxy support
|
||||
ENABLE_SOCKS5_PROXY=true
|
||||
NEXT_PUBLIC_ENABLE_SOCKS5_PROXY=true
|
||||
# HTTP_PROXY=http://127.0.0.1:7890
|
||||
# HTTPS_PROXY=http://127.0.0.1:7890
|
||||
# ALL_PROXY=socks5://127.0.0.1:7890
|
||||
# NO_PROXY=localhost,127.0.0.1
|
||||
|
||||
# TLS fingerprint spoofing (opt-in) — mimics Chrome 124 TLS handshake via wreq-js
|
||||
# Reduces risk of JA3/JA4 fingerprint-based blocking by providers (e.g., Google)
|
||||
# Requires wreq-js to be installed (included in dependencies)
|
||||
# ENABLE_TLS_FINGERPRINT=true
|
||||
|
||||
# Optional CLI runtime overrides (Docker/host integration)
|
||||
# CLI_MODE=auto
|
||||
# CLI_EXTRA_PATHS=/host-cli/bin
|
||||
# CLI_CONFIG_HOME=/root
|
||||
# CLI_ALLOW_CONFIG_WRITES=true
|
||||
# CLI_CLAUDE_BIN=claude
|
||||
# CLI_CODEX_BIN=codex
|
||||
# CLI_DROID_BIN=droid
|
||||
# CLI_OPENCLAW_BIN=openclaw
|
||||
# CLI_CURSOR_BIN=agent
|
||||
# CLI_CLINE_BIN=cline
|
||||
# CLI_ROO_BIN=roo
|
||||
# CLI_CONTINUE_BIN=cn
|
||||
|
||||
# Provider OAuth Credentials (optional — override hardcoded defaults)
|
||||
# These can also be set via data/provider-credentials.json
|
||||
# CLAUDE_OAUTH_CLIENT_ID=
|
||||
# GEMINI_OAUTH_CLIENT_ID=
|
||||
# GEMINI_OAUTH_CLIENT_SECRET=
|
||||
# GEMINI_CLI_OAUTH_CLIENT_ID=
|
||||
# GEMINI_CLI_OAUTH_CLIENT_SECRET=
|
||||
# CODEX_OAUTH_CLIENT_ID=
|
||||
# CODEX_OAUTH_CLIENT_SECRET=
|
||||
# QWEN_OAUTH_CLIENT_ID=
|
||||
# IFLOW_OAUTH_CLIENT_ID=
|
||||
# IFLOW_OAUTH_CLIENT_SECRET=
|
||||
# ANTIGRAVITY_OAUTH_CLIENT_ID=
|
||||
# ANTIGRAVITY_OAUTH_CLIENT_SECRET=
|
||||
|
||||
# API Key Providers (Phase 1 + Phase 4)
|
||||
# Add via Dashboard → Providers → Add API Key, or set here
|
||||
# DEEPSEEK_API_KEY=
|
||||
# GROQ_API_KEY=
|
||||
# XAI_API_KEY=
|
||||
# MISTRAL_API_KEY=
|
||||
# PERPLEXITY_API_KEY=
|
||||
# TOGETHER_API_KEY=
|
||||
# FIREWORKS_API_KEY=
|
||||
# CEREBRAS_API_KEY=
|
||||
# COHERE_API_KEY=
|
||||
# NVIDIA_API_KEY=
|
||||
|
||||
# Embedding Providers (optional — used by /v1/embeddings)
|
||||
# NEBIUS_API_KEY=
|
||||
# Provider keys above (openai, mistral, together, fireworks, nvidia) also work for embeddings
|
||||
|
||||
# Timeout settings
|
||||
# FETCH_TIMEOUT_MS=120000
|
||||
# STREAM_IDLE_TIMEOUT_MS=60000
|
||||
|
||||
# CORS configuration (default: * allows all origins)
|
||||
# CORS_ORIGINS=*
|
||||
|
||||
# Logging
|
||||
# LOG_LEVEL=info
|
||||
# LOG_FORMAT=text
|
||||
31
.github/dependabot.yml
vendored
Normal file
31
.github/dependabot.yml
vendored
Normal file
@@ -0,0 +1,31 @@
|
||||
version: 2
|
||||
updates:
|
||||
- package-ecosystem: "npm"
|
||||
directory: "/"
|
||||
schedule:
|
||||
interval: "weekly"
|
||||
day: "monday"
|
||||
commit-message:
|
||||
prefix: "deps"
|
||||
open-pull-requests-limit: 10
|
||||
groups:
|
||||
production:
|
||||
dependency-type: "production"
|
||||
development:
|
||||
dependency-type: "development"
|
||||
ignore:
|
||||
- dependency-name: "react"
|
||||
update-types: ["version-update:semver-major"]
|
||||
- dependency-name: "react-dom"
|
||||
update-types: ["version-update:semver-major"]
|
||||
- dependency-name: "next"
|
||||
update-types: ["version-update:semver-major"]
|
||||
- dependency-name: "eslint"
|
||||
update-types: ["version-update:semver-major"]
|
||||
- dependency-name: "eslint-config-next"
|
||||
update-types: ["version-update:semver-major"]
|
||||
|
||||
- package-ecosystem: "github-actions"
|
||||
directory: "/"
|
||||
schedule:
|
||||
interval: "weekly"
|
||||
110
.github/workflows/ci.yml
vendored
Normal file
110
.github/workflows/ci.yml
vendored
Normal file
@@ -0,0 +1,110 @@
|
||||
name: CI
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
pull_request:
|
||||
branches: [main]
|
||||
|
||||
concurrency:
|
||||
group: ${{ github.workflow }}-${{ github.ref }}
|
||||
cancel-in-progress: true
|
||||
|
||||
jobs:
|
||||
lint:
|
||||
name: Lint
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v6
|
||||
- uses: actions/setup-node@v6
|
||||
with:
|
||||
node-version: 22
|
||||
cache: npm
|
||||
- run: npm ci
|
||||
- run: npm run lint
|
||||
|
||||
security:
|
||||
name: Security Audit
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v6
|
||||
- uses: actions/setup-node@v6
|
||||
with:
|
||||
node-version: 22
|
||||
cache: npm
|
||||
- run: npm ci
|
||||
- name: Dependency audit
|
||||
run: npm audit --audit-level=high --omit=dev
|
||||
- name: Check for known vulnerabilities
|
||||
run: npx is-my-node-vulnerable || true
|
||||
|
||||
build:
|
||||
name: Build
|
||||
runs-on: ubuntu-latest
|
||||
strategy:
|
||||
matrix:
|
||||
node-version: [20, 22]
|
||||
steps:
|
||||
- uses: actions/checkout@v6
|
||||
- uses: actions/setup-node@v6
|
||||
with:
|
||||
node-version: ${{ matrix.node-version }}
|
||||
cache: npm
|
||||
- run: npm ci
|
||||
- run: npm run build
|
||||
|
||||
test-unit:
|
||||
name: Unit Tests
|
||||
runs-on: ubuntu-latest
|
||||
needs: build
|
||||
strategy:
|
||||
matrix:
|
||||
node-version: [20, 22]
|
||||
env:
|
||||
JWT_SECRET: ci-test-secret-with-sufficient-length-for-validation
|
||||
API_KEY_SECRET: ci-test-api-key-secret-long
|
||||
steps:
|
||||
- uses: actions/checkout@v6
|
||||
- uses: actions/setup-node@v6
|
||||
with:
|
||||
node-version: ${{ matrix.node-version }}
|
||||
cache: npm
|
||||
- run: npm ci
|
||||
- run: npm run test:unit
|
||||
|
||||
test-coverage:
|
||||
name: Coverage
|
||||
runs-on: ubuntu-latest
|
||||
needs: build
|
||||
env:
|
||||
JWT_SECRET: ci-test-secret-with-sufficient-length-for-validation
|
||||
API_KEY_SECRET: ci-test-api-key-secret-long
|
||||
steps:
|
||||
- uses: actions/checkout@v6
|
||||
- uses: actions/setup-node@v6
|
||||
with:
|
||||
node-version: 22
|
||||
cache: npm
|
||||
- run: npm ci
|
||||
- run: npm run test:coverage
|
||||
- name: Check coverage threshold
|
||||
run: |
|
||||
echo "Coverage report generated. Check output for threshold compliance."
|
||||
|
||||
test-e2e:
|
||||
name: E2E Tests
|
||||
runs-on: ubuntu-latest
|
||||
needs: build
|
||||
env:
|
||||
JWT_SECRET: ci-test-secret-with-sufficient-length-for-validation
|
||||
API_KEY_SECRET: ci-test-api-key-secret-long
|
||||
steps:
|
||||
- uses: actions/checkout@v6
|
||||
- uses: actions/setup-node@v6
|
||||
with:
|
||||
node-version: 22
|
||||
cache: npm
|
||||
- run: npm ci
|
||||
- run: npx playwright install --with-deps chromium
|
||||
- run: npm run build
|
||||
- run: npm run test:e2e
|
||||
22
.github/workflows/codex-review.yml
vendored
Normal file
22
.github/workflows/codex-review.yml
vendored
Normal file
@@ -0,0 +1,22 @@
|
||||
name: Codex PR Review
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
types: [opened, synchronize]
|
||||
|
||||
jobs:
|
||||
request-codex-review:
|
||||
runs-on: ubuntu-latest
|
||||
permissions:
|
||||
pull-requests: write
|
||||
steps:
|
||||
- name: Request Codex Review
|
||||
uses: actions/github-script@v8
|
||||
with:
|
||||
script: |
|
||||
await github.rest.issues.createComment({
|
||||
owner: context.repo.owner,
|
||||
repo: context.repo.repo,
|
||||
issue_number: context.payload.pull_request.number,
|
||||
body: '@codex review'
|
||||
});
|
||||
55
.github/workflows/docker-publish.yml
vendored
Normal file
55
.github/workflows/docker-publish.yml
vendored
Normal file
@@ -0,0 +1,55 @@
|
||||
name: Publish to Docker Hub
|
||||
|
||||
on:
|
||||
release:
|
||||
types: [published]
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
jobs:
|
||||
docker:
|
||||
name: Build & Push Docker Image
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v6
|
||||
|
||||
- name: Extract version from release tag
|
||||
id: version
|
||||
run: |
|
||||
VERSION="${GITHUB_REF_NAME}"
|
||||
VERSION="${VERSION#v}"
|
||||
echo "version=$VERSION" >> "$GITHUB_OUTPUT"
|
||||
echo "Publishing Docker image version: $VERSION"
|
||||
|
||||
- name: Set up Docker Buildx
|
||||
uses: docker/setup-buildx-action@v3
|
||||
|
||||
- name: Login to Docker Hub
|
||||
uses: docker/login-action@v3
|
||||
with:
|
||||
username: ${{ secrets.DOCKERHUB_USERNAME }}
|
||||
password: ${{ secrets.DOCKERHUB_TOKEN }}
|
||||
|
||||
- name: Build and push
|
||||
uses: docker/build-push-action@v6
|
||||
with:
|
||||
context: .
|
||||
target: runner-base
|
||||
push: true
|
||||
tags: |
|
||||
diegosouzapw/omniroute:${{ steps.version.outputs.version }}
|
||||
diegosouzapw/omniroute:latest
|
||||
cache-from: type=gha
|
||||
cache-to: type=gha,mode=max
|
||||
platforms: linux/amd64
|
||||
|
||||
- name: Update Docker Hub description
|
||||
uses: peter-evans/dockerhub-description@v5
|
||||
with:
|
||||
username: ${{ secrets.DOCKERHUB_USERNAME }}
|
||||
password: ${{ secrets.DOCKERHUB_TOKEN }}
|
||||
repository: diegosouzapw/omniroute
|
||||
short-description: "OmniRoute — Unified AI proxy. Route any LLM through one endpoint."
|
||||
readme-filepath: ./README.md
|
||||
42
.github/workflows/npm-publish.yml
vendored
Normal file
42
.github/workflows/npm-publish.yml
vendored
Normal file
@@ -0,0 +1,42 @@
|
||||
name: Publish to npm
|
||||
|
||||
on:
|
||||
release:
|
||||
types: [published]
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
id-token: write
|
||||
|
||||
jobs:
|
||||
publish:
|
||||
runs-on: ubuntu-latest
|
||||
environment: NPM_TOKEN
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v6
|
||||
|
||||
- name: Setup Node.js
|
||||
uses: actions/setup-node@v6
|
||||
with:
|
||||
node-version: 22
|
||||
registry-url: https://registry.npmjs.org
|
||||
|
||||
- name: Install dependencies
|
||||
run: npm ci
|
||||
|
||||
- name: Build standalone app
|
||||
run: npm run build:cli
|
||||
|
||||
- name: Sync version from release tag
|
||||
run: |
|
||||
VERSION="${GITHUB_REF_NAME}"
|
||||
# Remove 'v' prefix if present (v0.1.0 -> 0.1.0)
|
||||
VERSION="${VERSION#v}"
|
||||
npm version "$VERSION" --no-git-tag-version --allow-same-version
|
||||
echo "Publishing version: $VERSION"
|
||||
|
||||
- name: Publish to npm
|
||||
run: npm publish --access public
|
||||
env:
|
||||
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
|
||||
96
.gitignore
vendored
Normal file
96
.gitignore
vendored
Normal file
@@ -0,0 +1,96 @@
|
||||
# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
|
||||
|
||||
# dependencies
|
||||
/node_modules
|
||||
/.pnp
|
||||
.pnp.*
|
||||
.yarn/*
|
||||
!.yarn/patches
|
||||
!.yarn/plugins
|
||||
!.yarn/releases
|
||||
!.yarn/versions
|
||||
|
||||
# testing
|
||||
/coverage
|
||||
|
||||
# next.js
|
||||
/.next/
|
||||
/out/
|
||||
|
||||
# production
|
||||
/build
|
||||
/app
|
||||
cloud/*
|
||||
|
||||
# misc
|
||||
.DS_Store
|
||||
*.pem
|
||||
|
||||
# debug
|
||||
npm-debug.log*
|
||||
yarn-debug.log*
|
||||
yarn-error.log*
|
||||
.pnpm-debug.log*
|
||||
|
||||
# env files (can opt-in for committing if needed)
|
||||
.env*
|
||||
!.env.example
|
||||
|
||||
# vercel
|
||||
.vercel
|
||||
|
||||
# typescript
|
||||
*.tsbuildinfo
|
||||
next-env.d.ts
|
||||
|
||||
# data and logs
|
||||
data/
|
||||
logs/*
|
||||
|
||||
# analysis directories (generated, not tracked)
|
||||
.analysis/
|
||||
antigravity-manager-analysis/
|
||||
|
||||
# docs (allow specific tracked files)
|
||||
docs/*
|
||||
!docs/ARCHITECTURE.md
|
||||
!docs/CODEBASE_DOCUMENTATION.md
|
||||
!docs/CONTRIBUTING.md
|
||||
!docs/USER_GUIDE.md
|
||||
!docs/API_REFERENCE.md
|
||||
!docs/TROUBLESHOOTING.md
|
||||
!docs/EXECUTION_CONTEXT_PROVIDER_SYNC.md
|
||||
!docs/TASK_NEBIUS_BACKEND_ENABLEMENT.md
|
||||
!docs/frontend-backend-provider-gap-report.md
|
||||
!docs/openapi.yaml
|
||||
!docs/PLANO-IMPLANTACAO.md
|
||||
!docs/TASKS.md
|
||||
!docs/FASE-*.md
|
||||
!docs/adr/
|
||||
!docs/cli-tools/
|
||||
!docs/planning/
|
||||
!docs/improvement-plans/
|
||||
!docs/api/
|
||||
!docs/VM_DEPLOYMENT_GUIDE.md
|
||||
!docs/FEATURES.md
|
||||
!docs/screenshots/
|
||||
|
||||
# open-sse tests
|
||||
open-sse/test/*
|
||||
|
||||
# Ignore vscode AI rules
|
||||
.github/instructions/codacy.instructions.md
|
||||
|
||||
# Playwright
|
||||
test-results/
|
||||
playwright-report/
|
||||
blob-report/
|
||||
cloud/
|
||||
omnirouteCloud/
|
||||
omnirouteSite/
|
||||
|
||||
# Security Analysis (standalone project with own git)
|
||||
security-analysis/
|
||||
|
||||
# Deploy workflow (contains sensitive VPS credentials)
|
||||
.agent/workflows/deploy.md
|
||||
1
.husky/pre-commit
Normal file
1
.husky/pre-commit
Normal file
@@ -0,0 +1 @@
|
||||
npx lint-staged
|
||||
44
.npmignore
Normal file
44
.npmignore
Normal file
@@ -0,0 +1,44 @@
|
||||
# Database files - NEVER publish
|
||||
data/
|
||||
**/data/
|
||||
**/db.json
|
||||
|
||||
# Source code (pre-built app/ is published instead)
|
||||
src/
|
||||
open-sse/
|
||||
docs/
|
||||
tests/
|
||||
cloud/
|
||||
images/
|
||||
logs/
|
||||
scripts/
|
||||
|
||||
# Config/dev files
|
||||
*.md
|
||||
!README.md
|
||||
.gitignore
|
||||
.git/
|
||||
.github/
|
||||
.husky/
|
||||
.vscode/
|
||||
.env*
|
||||
eslint.config.mjs
|
||||
prettier.config.mjs
|
||||
postcss.config.mjs
|
||||
next.config.mjs
|
||||
tsconfig.json
|
||||
playwright.config.ts
|
||||
next-env.d.ts
|
||||
|
||||
# Docker
|
||||
docker-compose*.yml
|
||||
Dockerfile
|
||||
.dockerignore
|
||||
|
||||
# Misc
|
||||
restart.sh
|
||||
AGENTS.md
|
||||
|
||||
# Build artifacts (pre-built goes inside app/)
|
||||
.next/
|
||||
node_modules/
|
||||
20
.vscode/settings.json
vendored
Normal file
20
.vscode/settings.json
vendored
Normal file
@@ -0,0 +1,20 @@
|
||||
{
|
||||
"css.lint.unknownAtRules": "ignore",
|
||||
"sonarlint.rules": {
|
||||
"css:S4662": {
|
||||
"level": "off"
|
||||
},
|
||||
"javascript:S6747": {
|
||||
"level": "off"
|
||||
},
|
||||
"javascript:S7764": {
|
||||
"level": "off"
|
||||
},
|
||||
"javascript:S6772": {
|
||||
"level": "off"
|
||||
},
|
||||
"javascript:S3776": {
|
||||
"level": "off"
|
||||
}
|
||||
}
|
||||
}
|
||||
106
AGENTS.md
Normal file
106
AGENTS.md
Normal file
@@ -0,0 +1,106 @@
|
||||
# omniroute — Agent Guidelines
|
||||
|
||||
## Project
|
||||
|
||||
Unified AI proxy/router — route any LLM through one endpoint. Multi-provider support
|
||||
(OpenAI, Anthropic, Gemini, DeepSeek, Groq, xAI, Mistral, Fireworks, Cohere, etc.)
|
||||
|
||||
## Stack
|
||||
|
||||
- **Runtime**: Next.js 16 (App Router), Node.js, ES Modules
|
||||
- **Language**: TypeScript 5.9 (`src/`) + JavaScript (`open-sse/`)
|
||||
- **Database**: better-sqlite3 (SQLite) — `DATA_DIR` configurable, default `~/.omniroute/`
|
||||
- **Streaming**: SSE via `open-sse` internal package
|
||||
- **Styling**: Tailwind CSS v4
|
||||
- **Docker**: Multi-stage Dockerfile, 3 profiles (base / cli / host)
|
||||
|
||||
## Architecture
|
||||
|
||||
### Data Layer (`src/lib/db/`)
|
||||
|
||||
All persistence uses SQLite through domain-specific modules:
|
||||
|
||||
| Module | Responsibility |
|
||||
| -------------- | ------------------------------------------ |
|
||||
| `core.ts` | SQLite engine, migrations, WAL, encryption |
|
||||
| `providers.ts` | Provider connections & nodes |
|
||||
| `models.ts` | Model aliases, MITM aliases, custom models |
|
||||
| `combos.ts` | Combo configurations |
|
||||
| `apiKeys.ts` | API key management & validation |
|
||||
| `settings.ts` | Settings, pricing, proxy config |
|
||||
| `backup.ts` | Backup / restore operations |
|
||||
|
||||
`src/lib/localDb.ts` is a **re-export layer only** — all 27+ consumers import from it,
|
||||
but the real logic lives in `src/lib/db/`.
|
||||
|
||||
### Request Pipeline (`open-sse/`)
|
||||
|
||||
| Handler | Role |
|
||||
| ----------------------- | ------------------------------------------- |
|
||||
| `chatCore.js` | Main chat completions proxy (SSE / non-SSE) |
|
||||
| `responsesHandler.js` | OpenAI Responses API compat |
|
||||
| `responseTranslator.js` | Format translation for Responses API |
|
||||
| `embeddings.js` | Embedding proxy |
|
||||
| `imageGeneration.js` | Image generation proxy |
|
||||
| `sseParser.js` | SSE stream parser |
|
||||
| `usageExtractor.js` | Token usage extraction from responses |
|
||||
|
||||
Translation between provider formats: `open-sse/translator/`
|
||||
|
||||
### OAuth & Tokens (`src/lib/oauth/`)
|
||||
|
||||
18 modules handling OAuth flows, token refresh, and provider credentials.
|
||||
Default credentials are hardcoded in `src/lib/oauth/constants/oauth.ts`,
|
||||
overridable via env vars or `data/provider-credentials.json`.
|
||||
|
||||
### Supporting Systems
|
||||
|
||||
| System | Location |
|
||||
| -------------------------- | ------------------------------------------------- |
|
||||
| Usage tracking & analytics | `src/lib/usageDb.ts`, `src/lib/usageAnalytics.ts` |
|
||||
| Token health checks | `src/lib/tokenHealthCheck.ts` |
|
||||
| Cloud sync | `src/lib/cloudSync.ts` |
|
||||
| Proxy logging | `src/lib/proxyLogger.ts` |
|
||||
| Data paths resolution | `src/lib/dataPaths.ts` |
|
||||
|
||||
### Adding a New Provider
|
||||
|
||||
1. Register in `src/shared/constants/providers.ts`
|
||||
2. Add executor in `open-sse/executors/`
|
||||
3. Add translator rules in `open-sse/translator/` (if non-OpenAI format)
|
||||
4. Add OAuth config in `src/lib/oauth/constants/oauth.ts` (if OAuth-based)
|
||||
|
||||
## Review Focus
|
||||
|
||||
### Security
|
||||
|
||||
- No hardcoded API keys or secrets in commits
|
||||
- Auth middleware on all API routes
|
||||
- Input validation on user-facing endpoints
|
||||
- SQLite encryption key must not be logged
|
||||
|
||||
### Architecture
|
||||
|
||||
- DB operations go through `src/lib/db/` modules, never raw SQL in routes
|
||||
- Provider requests flow through `open-sse/handlers/`
|
||||
- Translations use `open-sse/translator/` modules
|
||||
- `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module
|
||||
|
||||
### Code Quality
|
||||
|
||||
- Consistent error handling with try/catch
|
||||
- Proper HTTP status codes
|
||||
- No memory leaks in SSE streams (abort signals, cleanup)
|
||||
- Rate limit headers must be parsed correctly
|
||||
|
||||
### Docker
|
||||
|
||||
- Dockerfile has two targets: `runner-base` and `runner-cli`
|
||||
- `docker-compose.yml` — development (3 profiles)
|
||||
- `docker-compose.prod.yml` — isolated production instance (port 20130)
|
||||
- Data persists in named volumes (`omniroute-data` / `omniroute-prod-data`)
|
||||
|
||||
### Review Mode
|
||||
|
||||
- Provide analysis and suggestions only
|
||||
- Focus on bugs, security, performance, and best practices
|
||||
248
CHANGELOG.md
Normal file
248
CHANGELOG.md
Normal file
@@ -0,0 +1,248 @@
|
||||
# Changelog
|
||||
|
||||
All notable changes to OmniRoute are documented in this file.
|
||||
|
||||
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
||||
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
||||
|
||||
---
|
||||
|
||||
## [0.9.0] — 2026-02-17
|
||||
|
||||
### Added
|
||||
|
||||
- 🌐 **Full multilingual README support** — Complete translations of README.md into 7 languages: Portuguese (pt-BR), Spanish (es), Russian (ru), Chinese Simplified (zh-CN), German (de), French (fr), Italian (it)
|
||||
- 🤖 **Agent showcase grid** — Modernized header with visual grid showcasing 10 AI coding agents (OpenClaw, NanoBot, PicoClaw, ZeroClaw, IronClaw, OpenCode, Codex CLI, Claude Code, Gemini CLI, Kilo Code)
|
||||
- 🖼️ **Provider logos** — Added logo assets for OpenClaw, NanoBot, PicoClaw, ZeroClaw, IronClaw, OpenCode
|
||||
- 🔌 **OpenAI-compatible provider validation fix** — Fallback validation via chat completions for providers that don't expose `/models` endpoint
|
||||
- 🛡️ **Red shield badges** — Replaced plain ❌ emoji with styled badge icons across all README files
|
||||
|
||||
---
|
||||
|
||||
## [0.8.8] — 2026-02-17
|
||||
|
||||
### Added
|
||||
|
||||
- 📊 **Analytics page redesign** — Rebuilt analytics dashboard with Recharts (SVG-based) charts replacing the previous implementation. New layout: stat cards → model usage bar chart → provider breakdown table with success rates and avg latency
|
||||
- 🎯 **6 global routing strategies** — Expanded from 3 (Fill-First, Round-Robin, P2C) to 6, adding Random, Least-Used, and Cost-Optimized. All strategies now have descriptions and icons in the Settings → Routing tab
|
||||
- 🔧 **Editable rate limits** — Rate limit defaults (RPM, Min Gap, Max Concurrent) are now editable in Settings → Resilience with save/cancel functionality. Values persist via the resilience API
|
||||
- 📋 **Policies in Resilience tab** — Moved PoliciesPanel (circuit breaker status + locked identifiers) from Security to Resilience tab for better logical grouping
|
||||
- 🧠 **Prompt Cache in AI tab** — Relocated CacheStatsCard from Advanced to AI tab alongside Thinking Budget and System Prompt
|
||||
|
||||
### Changed
|
||||
|
||||
- ♻️ **Settings page restructure** — Reorganized all settings tabs for better UX:
|
||||
- **Security**: Simplified to Login/Password and IP Access Control only
|
||||
- **Routing**: Expanded strategy grid with all 6 routing strategies
|
||||
- **Resilience**: Reordered cards (Provider Profiles → Rate Limiting → Circuit Breakers → Policies & Locked Identifiers)
|
||||
- **AI**: Now includes Thinking Budget, System Prompt, and Prompt Cache
|
||||
- **Advanced**: Simplified to only Global Proxy configuration
|
||||
- 🔄 **Backend routing strategies** — Implemented `random` (Fisher-Yates shuffle), `least-used` (sorted by `lastUsedAt`), `cost-optimized` (sorted by priority ascending), and fixed `p2c` (power-of-two-choices with health scoring) in `auth.ts`
|
||||
- 🔌 **Resilience API updates** — GET endpoint now merges saved rate limit defaults with constants; PATCH endpoint accepts both `profiles` and `defaults`
|
||||
- 📊 **Usage page split** — Refactored Usage page into "Request Logs" (with updated icon) and a new dedicated "Limits & Quotas" page
|
||||
|
||||
### Fixed
|
||||
|
||||
- 🐛 **Provider add error** — Improved error handling for API responses when adding new provider connections, with clear validation feedback
|
||||
|
||||
---
|
||||
|
||||
## [0.8.5] — 2026-02-17
|
||||
|
||||
> ### 🔷 MILESTONE: 100% TypeScript Migration
|
||||
>
|
||||
> **OmniRoute is now fully TypeScript.** The entire `src/` directory (API routes, components, services, lib, domain layer) and all 94 files in `open-sse/` have been migrated from JavaScript/JSX to TypeScript/TSX — with zero `@ts-ignore` annotations and zero TypeScript errors. This is a complete rewrite of the type layer across 200+ files.
|
||||
|
||||
### Added
|
||||
|
||||
- 🔒 **TLS fingerprint spoofing** — Implement browser-like TLS fingerprinting via `wreq-js` to bypass bot detection on providers that enforce TLS client fingerprint checks (`3dd0cc1`, PR #52)
|
||||
- 💾 **SQLite proxy log persistence** — Proxy request/response logs now persist to SQLite database, surviving server restarts. Previously, logs were lost on restart (`f1664fe`, PR #53)
|
||||
- 📋 **Unified test logging** — Shared `Logger` + Proxy logging infrastructure for all provider connection test flows. Consistent log formatting across batch and individual tests (`bce302e`, PR #55)
|
||||
|
||||
### Refactored
|
||||
|
||||
- 🔷 **Full TypeScript migration — `src/`** — Migrated the entire `src/` directory from JavaScript to TypeScript. All `.js`/`.jsx` files converted to `.ts`/`.tsx` with proper type annotations across API routes, lib modules, components, services, stores, domain layer, and shared utilities (`d0ca595`)
|
||||
- **Wave 1**: Shared component interfaces + EventTarget fixes (`dfdd2a2`)
|
||||
- **Wave 2**: Utils & services typed fields, Zustand stores, logger, sync scheduler (`89dd107`, `b2907cd`)
|
||||
- **Wave 3a**: Lib layer, DB, compliance, domain layer typed (`9e13fe2`)
|
||||
- **Wave 3b**: Usage, CLI runtime, SSE auth/logger typed (`a291abd`)
|
||||
- **Wave 3c**: OAuth services + server utils typed (`d62cf8d`)
|
||||
- **Wave 4a**: 7 API routes — providers, cli-tools, oauth (`7cdb923`)
|
||||
- **Wave 4b**: 7 more API routes — providers, test, usage, nodes (`5592c2e`)
|
||||
- **Wave 4c**: 8 files — components, SSE handlers, services (`d8ce9dc`)
|
||||
- **Dashboard hardening**: Resolve all TypeScript errors across dashboard pages (`7a463a3`, PR #61)
|
||||
- 🔷 **Full TypeScript migration — `open-sse/`** — Migrated all 94 `.js` files in the SSE routing engine to TypeScript (PR #62)
|
||||
- **Phase 1**: Rename all 94 `.js` → `.ts` files (`256e443`)
|
||||
- **Phase 6**: Reduce `@ts-ignore` from 231 → 186 with targeted fixes (`6a54b84`)
|
||||
- **Phase 7**: Eliminate ALL `@ts-ignore` annotations (186 → 0) and ALL TypeScript errors (237 → 0) — zero `@ts-ignore`, zero errors (`7b37a3c`)
|
||||
- Typing strategies: `Record<string, any>` for dynamic objects, optional function params, `as any` casts for custom Error/Array properties, `declare var EdgeRuntime` for edge compatibility, proper `fs`/`path` imports
|
||||
|
||||
### Fixed
|
||||
|
||||
- 🐛 **Qwen token refresh** — Detect `invalid_request` as unrecoverable error and switch broken test endpoints to `checkExpiry` method instead of failing silently (`1e0ffbc`, PR #60)
|
||||
- 🐛 **VPS batch test compatibility** — Eliminate HTTP self-calls in batch provider connection tests for VPS environments where localhost is unreachable (`a3bbbb5`, PR #54)
|
||||
- 🐛 **E2E test assertions** — Correct API endpoints and response format assertions in end-to-end tests (`92b5e66`)
|
||||
- 🐛 **CI coverage thresholds** — Lower coverage thresholds, use production server for E2E, block ESLint major upgrades from breaking CI (`3ca4b6b`, PR #51)
|
||||
|
||||
### Changed
|
||||
|
||||
- 📖 **Documentation update** — Updated all documentation to reflect JS → TS migration, corrected file extensions and import paths (`7ff8aa2`)
|
||||
- ⬆️ **CI/CD** — Bump `actions/checkout` v4 → v6, `actions/setup-node` v4 → v6, `peter-evans/dockerhub-description` v4 → v5
|
||||
|
||||
### Dependencies
|
||||
|
||||
- ⬆️ `undici` 7.21.0 → 7.22.0 (production)
|
||||
- ⬆️ `actions/checkout` 4 → 6
|
||||
- ⬆️ `actions/setup-node` 4 → 6
|
||||
- ⬆️ `peter-evans/dockerhub-description` 4 → 5
|
||||
- 🚫 `eslint` 10.0.0 blocked — major version incompatible with `eslint-config-next`
|
||||
|
||||
---
|
||||
|
||||
## [0.8.0] — 2026-02-16
|
||||
|
||||
### Added
|
||||
|
||||
- 🌐 **Official website** — [omniroute.online](https://omniroute.online) live with static site on Akamai VM + Cloudflare proxy
|
||||
- 🛡️ **Comprehensive SECURITY.md** — Full codebase audit documenting 10+ security features (AES-256-GCM, prompt injection guard, PII redaction, circuit breaker, etc.)
|
||||
- 📖 **Documentation tracking** — `USER_GUIDE.md`, `API_REFERENCE.md`, `TROUBLESHOOTING.md` now tracked in git
|
||||
- 🏷️ **Website badge** — Official website badge and links in README, npm, and Docker Hub
|
||||
- 🔗 **36+ providers** — Updated provider count across documentation
|
||||
|
||||
### Changed
|
||||
|
||||
- 📦 **npm homepage** — Points to `omniroute.online` instead of GitHub
|
||||
- 🐳 **Docker OCI labels** — Added `org.opencontainers.image.url` for Docker Hub
|
||||
- 🔒 **Security policy** — Updated supported versions, replaced email with GitHub Security Advisories
|
||||
|
||||
---
|
||||
|
||||
## [0.7.0] — 2026-02-16
|
||||
|
||||
### Added
|
||||
|
||||
- 🐳 **Docker Hub public image** — `diegosouzapw/omniroute` available on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute) with `latest` and versioned tags
|
||||
- 🔄 **Docker CI/CD** — GitHub Actions workflow (`docker-publish.yml`) auto-builds and pushes Docker image on every release
|
||||
- ☁️ **Akamai VM deployment** — Nanode 1GB instance created for remote hosting
|
||||
- 🎯 **Provider model filtering** — Filter model suggestions by selected provider in Translator and Chat Tester
|
||||
- 🔌 **CLI status badges** — Extract `CliStatusBadge` component; status visible on collapsed tool cards
|
||||
- ☁️ **Cloud connection UX** — GET status endpoint, toast feedback, and sidebar indicator for cloud sync
|
||||
- 🔐 **OAuth provider secrets** — Default cloud URL and OAuth provider secrets set via environment variables
|
||||
- ⚡ **Edge compatibility** — Replace `uuid` package with native `crypto.randomUUID()` for Cloudflare Workers compatibility
|
||||
|
||||
---
|
||||
|
||||
## [0.6.0] — 2026-02-16
|
||||
|
||||
### Added
|
||||
|
||||
- 💰 **Costs & Budget page** — Dedicated dashboard page for cost tracking and budget management
|
||||
- 📊 **Provider metrics display** — Show per-provider usage metrics and statistics
|
||||
- 📥 **Model import for passthrough providers** — Import models from API-compatible providers (Deepgram, AssemblyAI, NanoBanana)
|
||||
- 🎨 **App icon redesign** — New network node graph icon with updated color scheme
|
||||
|
||||
---
|
||||
|
||||
## [0.5.0] — 2026-02-15
|
||||
|
||||
### Added
|
||||
|
||||
- 🧪 **LLM Evaluations (Evals)** — Golden set testing framework with 4 match strategies (`exact`, `contains`, `regex`, `custom`)
|
||||
- 🎲 **Advanced combo strategies** — `random`, `least-used`, and `cost-optimized` balancing strategies for combos
|
||||
- 📊 **API key usage in Evals** — Evals tab uses API key auth for real LLM calls through the proxy
|
||||
- 🏷️ **Model availability badge** — Visual indicator for model availability per provider
|
||||
- 🎨 **Landing page retheme** — Updated landing page design with new aesthetic
|
||||
- 🧩 **Shared UI component library** — Refactored dashboard with reusable component library
|
||||
|
||||
### Fixed
|
||||
|
||||
- 🐛 Fix `TypeError` in `chat/completions` `ensureInitialized` call
|
||||
|
||||
---
|
||||
|
||||
## [0.4.0] — 2026-02-15
|
||||
|
||||
### Added
|
||||
|
||||
- 🧠 **LLM Gateway Intelligence** (Phase 9) — Smart routing, semantic caching, request idempotency, progress tracking
|
||||
- 📄 **Missing flows & pages** (Phase 8) — Error pages, UX components, telemetry dashboards
|
||||
- 🔧 **API & code quality** (Phase 7) — API restructuring, JSDoc documentation, code quality improvements
|
||||
- 📚 **Documentation restructuring** (Phase 10) — Component decomposition, docs cleanup
|
||||
- ✅ **26 action items** from critical analysis resolved
|
||||
|
||||
### Changed
|
||||
|
||||
- ♻️ **Architecture refactor** (Phase 5-6) — Domain persistence, policy engine, OAuth extraction, proxy decoupling
|
||||
|
||||
### Fixed
|
||||
|
||||
- 🐛 Fix CI build and lint failures
|
||||
- 🐛 Fix ghost import in `chatHelpers.js` SSE handling
|
||||
|
||||
---
|
||||
|
||||
## [0.3.0] — 2026-02-15
|
||||
|
||||
### Added
|
||||
|
||||
- ⚡ **Resilience system** — Exponential backoff, circuit breaker, anti-thundering herd mutex, Resilience UI settings page
|
||||
- 🖥️ **100% frontend API coverage** — 7 implementation batches covering all backend routes
|
||||
- 📊 **9 new API routes** — Budget, telemetry, compliance, tags, storage health, and more
|
||||
- 🧪 **Eval framework & compliance** — ADRs, accessibility, CLI specs, Playwright test specs (46 tasks)
|
||||
- 🏗️ **Pipeline integration** — 7 backend modules wired into request processing pipeline
|
||||
- 🔐 **Security hardening** — Phases 01–06 (input validation, CSRF, rate limiting, auth hardening)
|
||||
- 🤖 **Advanced features** — Phases 07–09 (domain extraction, error codes, request ID, fetch timeout)
|
||||
- 🔄 **Unrecoverable token handling** — Detect and mark connections as expired on fatal refresh errors
|
||||
|
||||
### Changed
|
||||
|
||||
- ♻️ Decompose `usageDb`, `handleSingleModelChat`, and UI components for maintainability
|
||||
- ⬇️ Downgrade ESLint v10 → v9 for `eslint-config-next` compatibility
|
||||
|
||||
---
|
||||
|
||||
## [0.2.0] — 2026-02-14
|
||||
|
||||
### Added
|
||||
|
||||
- 🛣️ **Advanced routing services** — Priority-based routing, global strategy configuration
|
||||
- 💰 **Cost analytics dashboard** — Token cost tracking and analytics visualization
|
||||
- 💎 **Pricing overhaul** — Comprehensive pricing data for all supported providers and models
|
||||
- 📦 **npm badge & CLI options** — npm version badge in README, CLI options table, automated release docs
|
||||
|
||||
---
|
||||
|
||||
## [0.1.0] — 2026-02-14
|
||||
|
||||
### Added
|
||||
|
||||
- 🎉 **Initial OmniRoute release** — Rebranded from 9router with full feature set
|
||||
- 🔄 **28 AI providers** — OpenAI, Claude, Gemini, Copilot, DeepSeek, Groq, xAI, Mistral, Qwen, iFlow, and more
|
||||
- 🎯 **Smart fallback** — 3-tier auto-routing (Subscription → Cheap → Free)
|
||||
- 🔀 **Format translation** — Seamless OpenAI ↔ Claude ↔ Gemini format conversion
|
||||
- 👥 **Multi-account support** — Multiple accounts per provider with round-robin
|
||||
- 🔐 **OAuth 2.0 (PKCE)** — Automatic token management and refresh
|
||||
- 📊 **Usage tracking** — Real-time quota monitoring with reset countdown
|
||||
- 🎨 **Custom combos** — Create model combinations with fallback chains
|
||||
- ☁️ **Cloud sync** — Sync configuration across devices via Cloudflare Worker
|
||||
- 📖 **OpenAPI specification** — Full API documentation
|
||||
- 🛡️ **SOCKS5 proxy support** — Outbound proxy for upstream provider calls
|
||||
- 🔌 **New endpoints** — `/v1/rerank`, `/v1/audio/*`, `/v1/moderations`
|
||||
- 📦 **npm CLI package** — `npm install -g omniroute` with auto-launch
|
||||
- 🐳 **Docker support** — Multi-stage Dockerfile with `base` and `cli` profiles
|
||||
- 🔒 **Security policy** — `SECURITY.md` with vulnerability reporting guidelines
|
||||
- 🧪 **CI/CD pipeline** — GitHub Actions for lint, build, test, and npm publish
|
||||
|
||||
---
|
||||
|
||||
[0.9.0]: https://github.com/diegosouzapw/OmniRoute/compare/v0.8.8...v0.9.0
|
||||
[0.8.8]: https://github.com/diegosouzapw/OmniRoute/compare/v0.8.5...v0.8.8
|
||||
[0.8.5]: https://github.com/diegosouzapw/OmniRoute/compare/v0.8.0...v0.8.5
|
||||
[0.8.0]: https://github.com/diegosouzapw/OmniRoute/compare/v0.7.0...v0.8.0
|
||||
[0.7.0]: https://github.com/diegosouzapw/OmniRoute/compare/v0.6.0...v0.7.0
|
||||
[0.6.0]: https://github.com/diegosouzapw/OmniRoute/compare/v0.5.0...v0.6.0
|
||||
[0.5.0]: https://github.com/diegosouzapw/OmniRoute/compare/v0.4.0...v0.5.0
|
||||
[0.4.0]: https://github.com/diegosouzapw/OmniRoute/compare/v0.3.0...v0.4.0
|
||||
[0.3.0]: https://github.com/diegosouzapw/OmniRoute/compare/v0.2.0...v0.3.0
|
||||
[0.2.0]: https://github.com/diegosouzapw/OmniRoute/compare/v0.1.0...v0.2.0
|
||||
[0.1.0]: https://github.com/diegosouzapw/OmniRoute/releases/tag/v0.1.0
|
||||
273
CONTRIBUTING.md
Normal file
273
CONTRIBUTING.md
Normal file
@@ -0,0 +1,273 @@
|
||||
# Contributing to OmniRoute
|
||||
|
||||
Thank you for your interest in contributing! This guide covers everything you need to get started.
|
||||
|
||||
---
|
||||
|
||||
## Development Setup
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- **Node.js** 20+ (recommended: 22 LTS)
|
||||
- **npm** 10+
|
||||
- **Git**
|
||||
|
||||
### Clone & Install
|
||||
|
||||
```bash
|
||||
git clone https://github.com/diegosouzapw/OmniRoute.git
|
||||
cd OmniRoute
|
||||
npm install
|
||||
```
|
||||
|
||||
### Environment Variables
|
||||
|
||||
```bash
|
||||
# Create your .env from the template
|
||||
cp .env.example .env
|
||||
|
||||
# Generate required secrets
|
||||
echo "JWT_SECRET=$(openssl rand -base64 48)" >> .env
|
||||
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 |
|
||||
|
||||
### Running Locally
|
||||
|
||||
```bash
|
||||
# Development mode (hot reload)
|
||||
npm run dev
|
||||
|
||||
# Production build
|
||||
npm run build
|
||||
npm run start
|
||||
|
||||
# Common port configuration
|
||||
PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
|
||||
```
|
||||
|
||||
Default URLs:
|
||||
|
||||
- **Dashboard**: `http://localhost:3000/dashboard`
|
||||
- **API**: `http://localhost:3000/v1`
|
||||
|
||||
---
|
||||
|
||||
## Git Workflow
|
||||
|
||||
> ⚠️ **NEVER commit directly to `main`.** Always use feature branches.
|
||||
|
||||
```bash
|
||||
git checkout -b feat/your-feature-name
|
||||
# ... make changes ...
|
||||
git commit -m "feat: describe your change"
|
||||
git push -u origin feat/your-feature-name
|
||||
# Open a Pull Request on GitHub
|
||||
```
|
||||
|
||||
### Branch Naming
|
||||
|
||||
| Prefix | Purpose |
|
||||
| ----------- | ------------------------- |
|
||||
| `feat/` | New features |
|
||||
| `fix/` | Bug fixes |
|
||||
| `refactor/` | Code restructuring |
|
||||
| `docs/` | Documentation changes |
|
||||
| `test/` | Test additions/fixes |
|
||||
| `chore/` | Tooling, CI, dependencies |
|
||||
|
||||
### Commit Messages
|
||||
|
||||
Follow [Conventional Commits](https://www.conventionalcommits.org/):
|
||||
|
||||
```
|
||||
feat: add circuit breaker for provider calls
|
||||
fix: resolve JWT secret validation edge case
|
||||
docs: update SECURITY.md with PII protection
|
||||
test: add observability unit tests
|
||||
refactor(db): consolidate rate limit tables
|
||||
```
|
||||
|
||||
Scopes: `db`, `sse`, `oauth`, `dashboard`, `api`, `cli`, `docker`, `ci`.
|
||||
|
||||
---
|
||||
|
||||
## Running Tests
|
||||
|
||||
```bash
|
||||
# All unit tests
|
||||
npm test
|
||||
npm run test:unit
|
||||
|
||||
# Specific test suites
|
||||
npm run test:security # Security tests
|
||||
npm run test:fixes # Fix verification tests
|
||||
|
||||
# With coverage
|
||||
npm run test:coverage
|
||||
|
||||
# E2E tests (requires Playwright)
|
||||
npm run test:e2e
|
||||
|
||||
# Lint + format check
|
||||
npm run lint
|
||||
npm run check
|
||||
```
|
||||
|
||||
Current test status: **368+ unit tests** covering:
|
||||
|
||||
- Provider translators and format conversion
|
||||
- Rate limiting, circuit breaker, and resilience
|
||||
- Semantic cache, idempotency, progress tracking
|
||||
- Database operations and schema
|
||||
- OAuth flows and authentication
|
||||
- API endpoint validation
|
||||
|
||||
---
|
||||
|
||||
## 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`)
|
||||
- **No `eval()`** — ESLint enforces `no-eval`, `no-implied-eval`, `no-new-func`
|
||||
- **Zod validation** — Use Zod schemas for API input validation
|
||||
|
||||
---
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
src/ # TypeScript (.ts / .tsx)
|
||||
├── app/ # Next.js App Router
|
||||
│ ├── (dashboard)/ # Dashboard pages (.tsx)
|
||||
│ ├── api/ # API routes (.ts)
|
||||
│ └── login/ # Auth pages (.tsx)
|
||||
├── domain/ # Domain types and response helpers (.ts)
|
||||
├── 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 # LowDB (JSON) storage
|
||||
├── shared/
|
||||
│ ├── components/ # React components (.tsx)
|
||||
│ ├── middleware/ # Correlation IDs, etc.
|
||||
│ ├── utils/ # Circuit breaker, sanitizer, etc.
|
||||
│ └── validation/ # Zod schemas
|
||||
└── sse/ # SSE chat handlers (.ts)
|
||||
|
||||
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
|
||||
|
||||
tests/
|
||||
├── unit/ # Node.js test runner (.test.mjs)
|
||||
└── e2e/ # Playwright tests
|
||||
|
||||
docs/ # Documentation
|
||||
├── USER_GUIDE.md # Provider setup, CLI integration
|
||||
├── API_REFERENCE.md # All endpoints
|
||||
├── TROUBLESHOOTING.md # Common issues
|
||||
├── ARCHITECTURE.md # System architecture
|
||||
└── adr/ # Architecture Decision Records
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Adding a New Provider
|
||||
|
||||
### Step 1: OAuth Service (if using OAuth)
|
||||
|
||||
Create `src/lib/oauth/services/your-provider.ts` extending `OAuthService`:
|
||||
|
||||
```typescript
|
||||
import { OAuthService } from "../OAuthService";
|
||||
|
||||
export class YourProviderService extends OAuthService {
|
||||
constructor() {
|
||||
super({
|
||||
name: "your-provider",
|
||||
authUrl: "https://provider.com/oauth/authorize",
|
||||
tokenUrl: "https://provider.com/oauth/token",
|
||||
clientId: "...",
|
||||
scopes: ["..."],
|
||||
});
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Step 2: Register Provider
|
||||
|
||||
Add to `src/lib/oauth/providers.ts`:
|
||||
|
||||
```typescript
|
||||
import { YourProviderService } from "./services/your-provider";
|
||||
// Add to the providers map
|
||||
```
|
||||
|
||||
### Step 3: Add Constants
|
||||
|
||||
Add provider constants in `src/lib/providerConstants.ts`:
|
||||
|
||||
- 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`.
|
||||
|
||||
### Step 6: Add Tests
|
||||
|
||||
Write unit tests in `tests/unit/` covering at minimum:
|
||||
|
||||
- Provider registration
|
||||
- Request/response translation
|
||||
- Error handling
|
||||
|
||||
---
|
||||
|
||||
## Pull Request Checklist
|
||||
|
||||
- [ ] Tests pass (`npm test`)
|
||||
- [ ] Linting passes (`npm run lint`)
|
||||
- [ ] Build succeeds (`npm run build`)
|
||||
- [ ] TypeScript types added for new public functions and interfaces
|
||||
- [ ] No hardcoded secrets or fallback values
|
||||
- [ ] CHANGELOG updated (if user-facing change)
|
||||
- [ ] Documentation updated (if applicable)
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Getting Help
|
||||
|
||||
- **Architecture**: See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)
|
||||
- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
|
||||
- **ADRs**: See `docs/adr/` for architectural decision records
|
||||
47
Dockerfile
Normal file
47
Dockerfile
Normal file
@@ -0,0 +1,47 @@
|
||||
FROM node:22-bookworm-slim AS builder
|
||||
WORKDIR /app
|
||||
|
||||
COPY package*.json ./
|
||||
RUN if [ -f package-lock.json ]; then npm ci --no-audit --no-fund; else npm install --no-audit --no-fund; fi
|
||||
|
||||
COPY . ./
|
||||
RUN mkdir -p /app/data && npm run build
|
||||
|
||||
FROM node:22-bookworm-slim AS runner-base
|
||||
WORKDIR /app
|
||||
|
||||
LABEL org.opencontainers.image.title="omniroute" \
|
||||
org.opencontainers.image.description="Unified AI proxy — route any LLM through one endpoint" \
|
||||
org.opencontainers.image.url="https://omniroute.online" \
|
||||
org.opencontainers.image.source="https://github.com/diegosouzapw/OmniRoute" \
|
||||
org.opencontainers.image.licenses="MIT"
|
||||
|
||||
ENV NODE_ENV=production
|
||||
ENV PORT=20128
|
||||
ENV HOSTNAME=0.0.0.0
|
||||
|
||||
# Runtime writable location for localDb when DATA_DIR is configured to /app/data
|
||||
RUN mkdir -p /app/data
|
||||
|
||||
COPY --from=builder /app/public ./public
|
||||
COPY --from=builder /app/.next/static ./.next/static
|
||||
COPY --from=builder /app/.next/standalone ./
|
||||
|
||||
EXPOSE 20128
|
||||
|
||||
HEALTHCHECK --interval=30s --timeout=5s --start-period=15s --retries=3 \
|
||||
CMD node -e "fetch('http://127.0.0.1:20128/api/settings').then(r=>{if(!r.ok)throw r.status}).catch(()=>process.exit(1))"
|
||||
|
||||
CMD ["node", "server.js"]
|
||||
|
||||
FROM runner-base AS runner-cli
|
||||
|
||||
# Install system dependencies required by openclaw (git+ssh references).
|
||||
RUN apt-get update \
|
||||
&& apt-get install -y --no-install-recommends git ca-certificates \
|
||||
&& rm -rf /var/lib/apt/lists/* \
|
||||
&& git config --system url."https://github.com/".insteadOf "ssh://git@github.com/"
|
||||
|
||||
# Install CLI tools globally. Separate layer from apt for better cache reuse.
|
||||
RUN npm install -g --no-audit --no-fund @openai/codex @anthropic-ai/claude-code droid openclaw@latest
|
||||
|
||||
21
LICENSE
Normal file
21
LICENSE
Normal file
@@ -0,0 +1,21 @@
|
||||
MIT License
|
||||
|
||||
Copyright (c) 2026 diegosouzapw
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
995
README.de.md
Normal file
995
README.de.md
Normal file
@@ -0,0 +1,995 @@
|
||||
<div align="center">
|
||||
<img src="./images/omniroute.png" alt="OmniRoute Dashboard" width="800"/>
|
||||
|
||||
# 🚀 OmniRoute — Das kostenlose AI-Gateway
|
||||
|
||||
### Höre nie auf zu programmieren. Intelligentes Routing zu **KOSTENLOSEN und günstigen KI-Modellen** mit automatischem Fallback.
|
||||
|
||||
_Dein universeller API-Proxy — ein Endpoint, 36+ Anbieter, null Ausfallzeit._
|
||||
|
||||
**Chat Completions • Embeddings • Bildgenerierung • Audio • Reranking • 100% TypeScript**
|
||||
|
||||
---
|
||||
|
||||
### 🤖 Kostenloser KI-Anbieter für deine Lieblings-Coding-Agenten
|
||||
|
||||
_Verbinde jedes KI-gesteuerte IDE- oder CLI-Tool über OmniRoute — kostenloses API-Gateway für unbegrenztes Programmieren._
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/cline/cline">
|
||||
<img src="./public/providers/openclaw.png" alt="OpenClaw" width="48"/><br/>
|
||||
<b>OpenClaw</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 205K</sub>
|
||||
</td>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/HKUDS/nanobot">
|
||||
<img src="./public/providers/nanobot.png" alt="NanoBot" width="48"/><br/>
|
||||
<b>NanoBot</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 20.9K</sub>
|
||||
</td>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/sipeed/picoclaw">
|
||||
<img src="./public/providers/picoclaw.jpg" alt="PicoClaw" width="48"/><br/>
|
||||
<b>PicoClaw</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 14.6K</sub>
|
||||
</td>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/zeroclaw-labs/zeroclaw">
|
||||
<img src="./public/providers/zeroclaw.png" alt="ZeroClaw" width="48"/><br/>
|
||||
<b>ZeroClaw</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 9.9K</sub>
|
||||
</td>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/nearai/ironclaw">
|
||||
<img src="./public/providers/ironclaw.png" alt="IronClaw" width="48"/><br/>
|
||||
<b>IronClaw</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 2.1K</sub>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/anomalyco/opencode">
|
||||
<img src="./public/providers/opencode.svg" alt="OpenCode" width="48"/><br/>
|
||||
<b>OpenCode</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 106K</sub>
|
||||
</td>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/openai/codex">
|
||||
<img src="./public/providers/codex.png" alt="Codex CLI" width="48"/><br/>
|
||||
<b>Codex CLI</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 60.8K</sub>
|
||||
</td>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/anthropics/claude-code">
|
||||
<img src="./public/providers/claude.png" alt="Claude Code" width="48"/><br/>
|
||||
<b>Claude Code</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 67.3K</sub>
|
||||
</td>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/google-gemini/gemini-cli">
|
||||
<img src="./public/providers/gemini-cli.png" alt="Gemini CLI" width="48"/><br/>
|
||||
<b>Gemini CLI</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 94.7K</sub>
|
||||
</td>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/Kilo-Org/kilocode">
|
||||
<img src="./public/providers/kilocode.png" alt="Kilo Code" width="48"/><br/>
|
||||
<b>Kilo Code</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 15.5K</sub>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<sub>📡 Alle Agenten verbinden sich über <code>http://localhost:20128/v1</code> oder <code>http://cloud.omniroute.online/v1</code> — eine Konfiguration, unbegrenzte Modelle und Kontingent</sub>
|
||||
|
||||
---
|
||||
|
||||
[](https://www.npmjs.com/package/omniroute)
|
||||
[](https://hub.docker.com/r/diegosouzapw/omniroute)
|
||||
[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
|
||||
[](https://omniroute.online)
|
||||
|
||||
[🌐 Website](https://omniroute.online) • [🚀 Schnellstart](#-schnellstart) • [💡 Funktionen](#-hauptfunktionen) • [📖 Doku](#-dokumentation) • [💰 Preise](#-preisübersicht)
|
||||
|
||||
🌐 **Verfügbar in:** [English](README.md) | [Português](README.pt-BR.md) | [Español](README.es.md) | [Русский](README.ru.md) | [中文](README.zh-CN.md) | [Deutsch](README.de.md) | [Français](README.fr.md) | [Italiano](README.it.md)
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## 🤔 Warum OmniRoute?
|
||||
|
||||
**Hör auf, Geld zu verschwenden und an Limits zu stoßen:**
|
||||
|
||||
- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> Abo-Kontingent verfällt jeden Monat ungenutzt
|
||||
- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> Rate-Limits stoppen dich mitten beim Programmieren
|
||||
- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> Teure APIs ($20-50/Monat pro Anbieter)
|
||||
- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> Manuelles Wechseln zwischen Anbietern
|
||||
|
||||
**OmniRoute löst das:**
|
||||
|
||||
- ✅ **Abos maximieren** — Kontingente tracken, alles vor dem Reset nutzen
|
||||
- ✅ **Automatischer Fallback** — Abo → API Key → Günstig → Kostenlos, null Ausfallzeit
|
||||
- ✅ **Multi-Account** — Round-Robin zwischen Konten pro Anbieter
|
||||
- ✅ **Universal** — Funktioniert mit Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, jedem CLI-Tool
|
||||
|
||||
---
|
||||
|
||||
## 🔄 So funktioniert's
|
||||
|
||||
```
|
||||
┌─────────────┐
|
||||
│ Dein CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)
|
||||
│ Tool │
|
||||
└──────┬──────┘
|
||||
│ http://localhost:20128/v1
|
||||
↓
|
||||
┌─────────────────────────────────────────┐
|
||||
│ OmniRoute (Smart Router) │
|
||||
│ • Format-Übersetzung (OpenAI ↔ Claude) │
|
||||
│ • Kontingent-Tracking + Embeddings + Bilder │
|
||||
│ • Automatische Token-Erneuerung │
|
||||
└──────┬──────────────────────────────────┘
|
||||
│
|
||||
├─→ [Tier 1: ABO] Claude Code, Codex, Gemini CLI
|
||||
│ ↓ Kontingent erschöpft
|
||||
├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM usw.
|
||||
│ ↓ Budget-Limit
|
||||
├─→ [Tier 3: GÜNSTIG] GLM ($0.6/1M), MiniMax ($0.2/1M)
|
||||
│ ↓ Budget-Limit
|
||||
└─→ [Tier 4: KOSTENLOS] iFlow, Qwen, Kiro (unbegrenzt)
|
||||
|
||||
Ergebnis: Nie aufhören zu programmieren, minimale Kosten
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚡ Schnellstart
|
||||
|
||||
**1. Global installieren:**
|
||||
|
||||
```bash
|
||||
npm install -g omniroute
|
||||
omniroute
|
||||
```
|
||||
|
||||
🎉 Das Dashboard öffnet sich unter `http://localhost:20128`
|
||||
|
||||
| Befehl | Beschreibung |
|
||||
| ----------------------- | ----------------------------------- |
|
||||
| `omniroute` | Server starten (Standardport 20128) |
|
||||
| `omniroute --port 3000` | Benutzerdefinierten Port verwenden |
|
||||
| `omniroute --no-open` | Browser nicht automatisch öffnen |
|
||||
| `omniroute --help` | Hilfe anzeigen |
|
||||
|
||||
**2. KOSTENLOSEN Anbieter verbinden:**
|
||||
|
||||
Dashboard → Anbieter → **Claude Code** oder **Antigravity** verbinden → OAuth Login → Fertig!
|
||||
|
||||
**3. In deinem CLI-Tool verwenden:**
|
||||
|
||||
```
|
||||
Claude Code/Codex/Gemini CLI/OpenClaw/Cursor/Cline Einstellungen:
|
||||
Endpoint: http://localhost:20128/v1
|
||||
API Key: [vom Dashboard kopieren]
|
||||
Model: if/kimi-k2-thinking
|
||||
```
|
||||
|
||||
**Das war's!** Beginne mit KOSTENLOSEN KI-Modellen zu programmieren.
|
||||
|
||||
**Alternative — aus Quellcode ausführen:**
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
npm install
|
||||
PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🐳 Docker
|
||||
|
||||
OmniRoute ist als öffentliches Docker-Image auf [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute) verfügbar.
|
||||
|
||||
**Schnellstart:**
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
--name omniroute \
|
||||
--restart unless-stopped \
|
||||
-p 20128:20128 \
|
||||
-v omniroute-data:/app/data \
|
||||
diegosouzapw/omniroute:latest
|
||||
```
|
||||
|
||||
**Mit Umgebungsdatei:**
|
||||
|
||||
```bash
|
||||
# .env kopieren und bearbeiten
|
||||
cp .env.example .env
|
||||
|
||||
docker run -d \
|
||||
--name omniroute \
|
||||
--restart unless-stopped \
|
||||
--env-file .env \
|
||||
-p 20128:20128 \
|
||||
-v omniroute-data:/app/data \
|
||||
diegosouzapw/omniroute:latest
|
||||
```
|
||||
|
||||
**Mit Docker Compose:**
|
||||
|
||||
```bash
|
||||
# Basisprofil (ohne CLI-Tools)
|
||||
docker compose --profile base up -d
|
||||
|
||||
# CLI-Profil (Claude Code, Codex, OpenClaw integriert)
|
||||
docker compose --profile cli up -d
|
||||
```
|
||||
|
||||
| Image | Tag | Größe | Beschreibung |
|
||||
| ------------------------ | -------- | ------ | ------------------------ |
|
||||
| `diegosouzapw/omniroute` | `latest` | ~250MB | Letztes stabiles Release |
|
||||
| `diegosouzapw/omniroute` | `0.9.0` | ~250MB | Aktuelle Version |
|
||||
|
||||
---
|
||||
|
||||
## 💰 Preisübersicht
|
||||
|
||||
| Tier | Anbieter | Kosten | Kontingent-Reset | Am besten für |
|
||||
| ---------------- | ----------------- | ---------------------------- | ------------------- | ----------------------- |
|
||||
| **💳 ABO** | Claude Code (Pro) | $20/Monat | 5h + wöchentlich | Bereits abonniert |
|
||||
| | Codex (Plus/Pro) | $20-200/Monat | 5h + wöchentlich | OpenAI-Nutzer |
|
||||
| | Gemini CLI | **KOSTENLOS** | 180K/Monat + 1K/Tag | Alle! |
|
||||
| | GitHub Copilot | $10-19/Monat | Monatlich | GitHub-Nutzer |
|
||||
| **🔑 API KEY** | NVIDIA NIM | **KOSTENLOS** (1000 Credits) | Einmalig | Kostenloses Testen |
|
||||
| | DeepSeek | Nach Verbrauch | Keiner | Bestes Preis-Leistung |
|
||||
| | Groq | Gratis-Stufe + bezahlt | Begrenzt | Ultra-schnelle Inferenz |
|
||||
| | xAI (Grok) | Nach Verbrauch | Keiner | Grok-Modelle |
|
||||
| | Mistral | Gratis-Stufe + bezahlt | Begrenzt | Europäische KI |
|
||||
| | OpenRouter | Nach Verbrauch | Keiner | 100+ Modelle |
|
||||
| **💰 GÜNSTIG** | GLM-4.7 | $0.6/1M | Täglich 10h | Budget-Backup |
|
||||
| | MiniMax M2.1 | $0.2/1M | 5h rotierend | Günstigste Option |
|
||||
| | Kimi K2 | $9/Monat fest | 10M Token/Monat | Vorhersagbare Kosten |
|
||||
| **🆓 KOSTENLOS** | iFlow | $0 | Unbegrenzt | 8 kostenlose Modelle |
|
||||
| | Qwen | $0 | Unbegrenzt | 3 kostenlose Modelle |
|
||||
| | Kiro | $0 | Unbegrenzt | Kostenloses Claude |
|
||||
|
||||
**💡 Profi-Tipp:** Starte mit Gemini CLI (180K gratis/Monat) + iFlow (unbegrenzt gratis) = $0 Kosten!
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Anwendungsfälle
|
||||
|
||||
### Fall 1: „Ich habe ein Claude Pro Abo"
|
||||
|
||||
**Problem:** Kontingent verfällt ungenutzt, Rate-Limits während intensivem Programmieren
|
||||
|
||||
```
|
||||
Combo: "maximize-claude"
|
||||
1. cc/claude-opus-4-6 (Abo voll ausnutzen)
|
||||
2. glm/glm-4.7 (günstiges Backup bei erschöpftem Kontingent)
|
||||
3. if/kimi-k2-thinking (kostenloser Notfall-Fallback)
|
||||
|
||||
Monatliche Kosten: $20 (Abo) + ~$5 (Backup) = $25 gesamt
|
||||
vs. $20 + an Limits stoßen = Frustration
|
||||
```
|
||||
|
||||
### Fall 2: „Ich will null Kosten"
|
||||
|
||||
**Problem:** Kann sich Abos nicht leisten, braucht zuverlässige KI zum Programmieren
|
||||
|
||||
```
|
||||
Combo: "free-forever"
|
||||
1. gc/gemini-3-flash (180K gratis/Monat)
|
||||
2. if/kimi-k2-thinking (unbegrenzt gratis)
|
||||
3. qw/qwen3-coder-plus (unbegrenzt gratis)
|
||||
|
||||
Monatliche Kosten: $0
|
||||
Qualität: Produktionsreife Modelle
|
||||
```
|
||||
|
||||
### Fall 3: „Ich muss 24/7 programmieren, ohne Unterbrechungen"
|
||||
|
||||
**Problem:** Enge Deadlines, kann sich keine Ausfallzeit leisten
|
||||
|
||||
```
|
||||
Combo: "always-on"
|
||||
1. cc/claude-opus-4-6 (beste Qualität)
|
||||
2. cx/gpt-5.2-codex (zweites Abo)
|
||||
3. glm/glm-4.7 (günstig, täglicher Reset)
|
||||
4. minimax/MiniMax-M2.1 (günstigste, 5h Reset)
|
||||
5. if/kimi-k2-thinking (unbegrenzt kostenlos)
|
||||
|
||||
Ergebnis: 5 Fallback-Ebenen = null Ausfallzeit
|
||||
```
|
||||
|
||||
### Fall 4: „Ich will KOSTENLOSE KI in OpenClaw"
|
||||
|
||||
**Problem:** Braucht KI-Assistenz in Messaging-Apps, komplett kostenlos
|
||||
|
||||
```
|
||||
Combo: "openclaw-free"
|
||||
1. if/glm-4.7 (unbegrenzt kostenlos)
|
||||
2. if/minimax-m2.1 (unbegrenzt kostenlos)
|
||||
3. if/kimi-k2-thinking (unbegrenzt kostenlos)
|
||||
|
||||
Monatliche Kosten: $0
|
||||
Zugang über: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 💡 Hauptfunktionen
|
||||
|
||||
### 🧠 Routing & Intelligenz
|
||||
|
||||
| Funktion | Was es macht |
|
||||
| ------------------------------------ | ------------------------------------------------------------------------------ |
|
||||
| 🎯 **Intelligenter 4-Tier-Fallback** | Auto-Routing: Abo → API Key → Günstig → Kostenlos |
|
||||
| 📊 **Echtzeit-Kontingent-Tracking** | Live Token-Zählung + Reset-Countdown pro Anbieter |
|
||||
| 🔄 **Format-Übersetzung** | OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro nahtlos |
|
||||
| 👥 **Multi-Account-Unterstützung** | Mehrere Konten pro Anbieter mit intelligenter Auswahl |
|
||||
| 🔄 **Auto-Token-Erneuerung** | OAuth-Token werden automatisch mit Wiederholungen erneuert |
|
||||
| 🎨 **Benutzerdefinierte Combos** | 6 Strategien: fill-first, round-robin, p2c, random, least-used, cost-optimized |
|
||||
| 🧩 **Benutzerdefinierte Modelle** | Jede Modell-ID zu jedem Anbieter hinzufügen |
|
||||
| 🌐 **Wildcard-Router** | `provider/*` Muster dynamisch an jeden Anbieter routen |
|
||||
| 🧠 **Reasoning-Budget** | Passthrough, auto, custom und adaptive Modi für Reasoning-Modelle |
|
||||
| 💬 **System Prompt Injection** | Globaler System Prompt für alle Anfragen |
|
||||
| 📄 **API Responses** | Volle Unterstützung der OpenAI Responses API (`/v1/responses`) für Codex |
|
||||
|
||||
### 🎵 Multi-Modale APIs
|
||||
|
||||
| Funktion | Was es macht |
|
||||
| -------------------------- | ------------------------------------------------- |
|
||||
| 🖼️ **Bildgenerierung** | `/v1/images/generations` — 4 Anbieter, 9+ Modelle |
|
||||
| 📐 **Embeddings** | `/v1/embeddings` — 6 Anbieter, 9+ Modelle |
|
||||
| 🎤 **Audio-Transkription** | `/v1/audio/transcriptions` — Whisper-kompatibel |
|
||||
| 🔊 **Text-zu-Sprache** | `/v1/audio/speech` — Multi-Anbieter Audiosynthese |
|
||||
| 🛡️ **Moderationen** | `/v1/moderations` — Sicherheitsüberprüfungen |
|
||||
| 🔀 **Reranking** | `/v1/rerank` — Dokumenten-Relevanz-Neuordnung |
|
||||
|
||||
### 🛡️ Resilienz & Sicherheit
|
||||
|
||||
| Funktion | Was es macht |
|
||||
| ------------------------------- | -------------------------------------------------------------------- |
|
||||
| 🔌 **Circuit Breaker** | Auto-Öffnung/-Schließung pro Anbieter mit konfigurierbaren Schwellen |
|
||||
| 🛡️ **Anti-Thundering Herd** | Mutex + Semaphor Rate-Limit für API-Key-Anbieter |
|
||||
| 🧠 **Semantischer Cache** | Zwei-Ebenen-Cache (Signatur + Semantik) senkt Kosten und Latenz |
|
||||
| ⚡ **Anfrage-Idempotenz** | 5s Dedup-Fenster für doppelte Anfragen |
|
||||
| 🔒 **TLS-Fingerprint-Spoofing** | Bot-Erkennung umgehen via wreq-js |
|
||||
| 🌐 **IP-Filterung** | Allowlist/Blocklist für API-Zugriffskontrolle |
|
||||
| 📊 **Editierbare Rate-Limits** | Konfigurierbare RPM, minimaler Abstand, max. Konkurrenz |
|
||||
|
||||
### 📊 Observability & Analytics
|
||||
|
||||
| Funktion | Was es macht |
|
||||
| ---------------------------- | -------------------------------------------------------------- |
|
||||
| 📝 **Anfrage-Logs** | Debug-Modus mit vollständigen Request/Response-Logs |
|
||||
| 💾 **SQLite-Logs** | Persistente Proxy-Logs überleben Neustarts |
|
||||
| 📊 **Analytics-Dashboard** | Recharts: Statistik-Karten, Nutzungsdiagramm, Anbieter-Tabelle |
|
||||
| 📈 **Fortschritts-Tracking** | Opt-in SSE-Fortschrittsereignisse für Streaming |
|
||||
| 🧪 **LLM-Evaluierungen** | Testen mit Golden Set und 4 Match-Strategien |
|
||||
| 🔍 **Anfrage-Telemetrie** | p50/p95/p99 Latenz-Aggregation + X-Request-Id Tracking |
|
||||
| 📋 **Logs + Kontingente** | Dedizierte Seiten für Log-Browsing und Kontingent-Tracking |
|
||||
| 🏥 **Health Dashboard** | Uptime, Circuit-Breaker-Status, Lockouts, Cache-Statistiken |
|
||||
| 💰 **Kosten-Tracking** | Budget-Management + Preiseinstellung pro Modell |
|
||||
|
||||
### ☁️ Deployment & Sync
|
||||
|
||||
| Funktion | Was es macht |
|
||||
| -------------------------- | ----------------------------------------------------------------------------- |
|
||||
| 💾 **Cloud Sync** | Einstellungen zwischen Geräten via Cloudflare Workers synchronisieren |
|
||||
| 🌐 **Überall deployen** | Localhost, VPS, Docker, Cloudflare Workers |
|
||||
| 🔑 **API-Key-Verwaltung** | API-Keys pro Anbieter generieren, rotieren und einschränken |
|
||||
| 🧙 **Setup-Assistent** | 4-Schritte geführtes Setup für neue Nutzer |
|
||||
| 🔧 **CLI Tools Dashboard** | Ein-Klick-Konfiguration für Claude, Codex, Cline, OpenClaw, Kilo, Antigravity |
|
||||
| 🔄 **DB-Backups** | Automatisches Backup und Wiederherstellung aller Einstellungen |
|
||||
|
||||
<details>
|
||||
<summary><b>📖 Funktionsdetails</b></summary>
|
||||
|
||||
### 🎯 Intelligenter 4-Tier-Fallback
|
||||
|
||||
Erstelle Combos mit automatischem Fallback:
|
||||
|
||||
```
|
||||
Combo: "my-coding-stack"
|
||||
1. cc/claude-opus-4-6 (dein Abo)
|
||||
2. nvidia/llama-3.3-70b (kostenlose NVIDIA API)
|
||||
3. glm/glm-4.7 (günstiges Backup, $0.6/1M)
|
||||
4. if/kimi-k2-thinking (kostenloser Fallback)
|
||||
|
||||
→ Wechselt automatisch bei erschöpftem Kontingent oder Fehlern
|
||||
```
|
||||
|
||||
### 📊 Echtzeit-Kontingent-Tracking
|
||||
|
||||
- Token-Verbrauch pro Anbieter
|
||||
- Reset-Countdown (5 Stunden, täglich, wöchentlich)
|
||||
- Kostenabschätzung für bezahlte Stufen
|
||||
- Monatliche Ausgabenberichte
|
||||
|
||||
### 🔄 Format-Übersetzung
|
||||
|
||||
Nahtlose Übersetzung zwischen Formaten:
|
||||
|
||||
- **OpenAI** ↔ **Claude** ↔ **Gemini** ↔ **OpenAI Responses**
|
||||
- Dein CLI sendet OpenAI-Format → OmniRoute übersetzt → Anbieter empfängt natives Format
|
||||
- Funktioniert mit jedem Tool, das benutzerdefinierte OpenAI-Endpoints unterstützt
|
||||
|
||||
### 👥 Multi-Account-Unterstützung
|
||||
|
||||
- Mehrere Konten pro Anbieter hinzufügen
|
||||
- Automatisches Round-Robin oder prioritätsbasiertes Routing
|
||||
- Fallback zum nächsten Konto bei Kontingent-Erschöpfung
|
||||
|
||||
### 🔄 Auto-Token-Erneuerung
|
||||
|
||||
- OAuth-Token werden automatisch vor Ablauf erneuert
|
||||
- Keine manuelle Neuauthentifizierung nötig
|
||||
- Nahtlose Erfahrung über alle Anbieter
|
||||
|
||||
### 🎨 Benutzerdefinierte Combos
|
||||
|
||||
- Unbegrenzte Modell-Kombinationen erstellen
|
||||
- 6 Strategien: fill-first, round-robin, power-of-two-choices, random, least-used, cost-optimized
|
||||
- Combos zwischen Geräten mit Cloud Sync teilen
|
||||
|
||||
### 🏥 Health Dashboard
|
||||
|
||||
- Systemstatus (Uptime, Version, Speichernutzung)
|
||||
- Circuit-Breaker-Status pro Anbieter (Closed/Open/Half-Open)
|
||||
- Rate-Limit-Status und aktive Lockouts
|
||||
- Signatur-Cache-Statistiken
|
||||
- Latenz-Telemetrie (p50/p95/p99) + Prompt-Cache
|
||||
- Gesundheitsstatus mit einem Klick zurücksetzen
|
||||
|
||||
### 🔧 Übersetzer-Playground
|
||||
|
||||
- Debug, Test und Visualisierung von API-Format-Übersetzungen
|
||||
- Anfragen senden und sehen, wie OmniRoute zwischen Anbieter-Formaten übersetzt
|
||||
- Unschätzbar für Integrationsprobleme
|
||||
|
||||
### 💾 Cloud Sync
|
||||
|
||||
- Anbieter, Combos und Einstellungen zwischen Geräten synchronisieren
|
||||
- Automatische Hintergrundsynchronisierung
|
||||
- Sichere verschlüsselte Speicherung
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## 📖 Einrichtungsanleitung
|
||||
|
||||
<details>
|
||||
<summary><b>💳 Abo-Anbieter</b></summary>
|
||||
|
||||
### Claude Code (Pro/Max)
|
||||
|
||||
```bash
|
||||
Dashboard → Anbieter → Claude Code verbinden
|
||||
→ OAuth Login → Automatische Token-Erneuerung
|
||||
→ 5h + wöchentliches Kontingent-Tracking
|
||||
|
||||
Modelle:
|
||||
cc/claude-opus-4-6
|
||||
cc/claude-sonnet-4-5-20250929
|
||||
cc/claude-haiku-4-5-20251001
|
||||
```
|
||||
|
||||
**Profi-Tipp:** Opus für komplexe Aufgaben, Sonnet für Geschwindigkeit. OmniRoute trackt Kontingent pro Modell!
|
||||
|
||||
### OpenAI Codex (Plus/Pro)
|
||||
|
||||
```bash
|
||||
Dashboard → Anbieter → Codex verbinden
|
||||
→ OAuth Login (Port 1455)
|
||||
→ 5h + wöchentlicher Reset
|
||||
|
||||
Modelle:
|
||||
cx/gpt-5.2-codex
|
||||
cx/gpt-5.1-codex-max
|
||||
```
|
||||
|
||||
### Gemini CLI (KOSTENLOS 180K/Monat!)
|
||||
|
||||
```bash
|
||||
Dashboard → Anbieter → Gemini CLI verbinden
|
||||
→ Google OAuth
|
||||
→ 180K Completions/Monat + 1K/Tag
|
||||
|
||||
Modelle:
|
||||
gc/gemini-3-flash-preview
|
||||
gc/gemini-2.5-pro
|
||||
```
|
||||
|
||||
**Bester Wert:** Riesiger Gratis-Tarif! Vor bezahlten Stufen nutzen.
|
||||
|
||||
### GitHub Copilot
|
||||
|
||||
```bash
|
||||
Dashboard → Anbieter → GitHub verbinden
|
||||
→ OAuth via GitHub
|
||||
→ Monatlicher Reset (1. des Monats)
|
||||
|
||||
Modelle:
|
||||
gh/gpt-5
|
||||
gh/claude-4.5-sonnet
|
||||
gh/gemini-3-pro
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>🔑 API-Key-Anbieter</b></summary>
|
||||
|
||||
### NVIDIA NIM (KOSTENLOS 1000 Credits!)
|
||||
|
||||
1. Registrieren: [build.nvidia.com](https://build.nvidia.com)
|
||||
2. Kostenlosen API-Key holen (1000 Inferenz-Credits inklusive)
|
||||
3. Dashboard → Anbieter hinzufügen → NVIDIA NIM:
|
||||
- API Key: `nvapi-your-key`
|
||||
|
||||
**Modelle:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct` und 50+ weitere
|
||||
|
||||
**Profi-Tipp:** OpenAI-kompatible API — funktioniert perfekt mit OmniRoutes Format-Übersetzung!
|
||||
|
||||
### DeepSeek
|
||||
|
||||
1. Registrieren: [platform.deepseek.com](https://platform.deepseek.com)
|
||||
2. API-Key holen
|
||||
3. Dashboard → Anbieter hinzufügen → DeepSeek
|
||||
|
||||
**Modelle:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`
|
||||
|
||||
### Groq (Gratis-Stufe verfügbar!)
|
||||
|
||||
1. Registrieren: [console.groq.com](https://console.groq.com)
|
||||
2. API-Key holen (Gratis-Stufe inklusive)
|
||||
3. Dashboard → Anbieter hinzufügen → Groq
|
||||
|
||||
**Modelle:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`
|
||||
|
||||
**Profi-Tipp:** Ultra-schnelle Inferenz — am besten für Echtzeit-Programmierung!
|
||||
|
||||
### OpenRouter (100+ Modelle)
|
||||
|
||||
1. Registrieren: [openrouter.ai](https://openrouter.ai)
|
||||
2. API-Key holen
|
||||
3. Dashboard → Anbieter hinzufügen → OpenRouter
|
||||
|
||||
**Modelle:** Zugang zu 100+ Modellen aller großen Anbieter über einen einzigen API-Key.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>💰 Günstige Anbieter (Backup)</b></summary>
|
||||
|
||||
### GLM-4.7 (Täglicher Reset, $0.6/1M)
|
||||
|
||||
1. Registrieren: [Zhipu AI](https://open.bigmodel.cn/)
|
||||
2. API-Key aus dem Coding Plan holen
|
||||
3. Dashboard → API Key hinzufügen:
|
||||
- Anbieter: `glm`
|
||||
- API Key: `your-key`
|
||||
|
||||
**Nutze:** `glm/glm-4.7`
|
||||
|
||||
**Profi-Tipp:** Der Coding Plan bietet 3× Kontingent zu 1/7 der Kosten! Täglicher Reset um 10:00.
|
||||
|
||||
### MiniMax M2.1 (5h Reset, $0.20/1M)
|
||||
|
||||
1. Registrieren: [MiniMax](https://www.minimax.io/)
|
||||
2. API-Key holen
|
||||
3. Dashboard → API Key hinzufügen
|
||||
|
||||
**Nutze:** `minimax/MiniMax-M2.1`
|
||||
|
||||
**Profi-Tipp:** Günstigste Option für langen Kontext (1M Token)!
|
||||
|
||||
### Kimi K2 ($9/Monat fest)
|
||||
|
||||
1. Abonnieren: [Moonshot AI](https://platform.moonshot.ai/)
|
||||
2. API-Key holen
|
||||
3. Dashboard → API Key hinzufügen
|
||||
|
||||
**Nutze:** `kimi/kimi-latest`
|
||||
|
||||
**Profi-Tipp:** Feste $9/Monat für 10M Token = $0.90/1M effektive Kosten!
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>🆓 KOSTENLOSE Anbieter (Notfall-Backup)</b></summary>
|
||||
|
||||
### iFlow (8 KOSTENLOSE Modelle)
|
||||
|
||||
```bash
|
||||
Dashboard → iFlow verbinden
|
||||
→ iFlow OAuth Login
|
||||
→ Unbegrenzte Nutzung
|
||||
|
||||
Modelle:
|
||||
if/kimi-k2-thinking
|
||||
if/qwen3-coder-plus
|
||||
if/glm-4.7
|
||||
if/minimax-m2
|
||||
if/deepseek-r1
|
||||
```
|
||||
|
||||
### Qwen (3 KOSTENLOSE Modelle)
|
||||
|
||||
```bash
|
||||
Dashboard → Qwen verbinden
|
||||
→ Geräte-Code-Autorisierung
|
||||
→ Unbegrenzte Nutzung
|
||||
|
||||
Modelle:
|
||||
qw/qwen3-coder-plus
|
||||
qw/qwen3-coder-flash
|
||||
```
|
||||
|
||||
### Kiro (Kostenloses Claude)
|
||||
|
||||
```bash
|
||||
Dashboard → Kiro verbinden
|
||||
→ AWS Builder ID oder Google/GitHub
|
||||
→ Unbegrenzte Nutzung
|
||||
|
||||
Modelle:
|
||||
kr/claude-sonnet-4.5
|
||||
kr/claude-haiku-4.5
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>🎨 Combos erstellen</b></summary>
|
||||
|
||||
### Beispiel 1: Abo maximieren → Günstiges Backup
|
||||
|
||||
```
|
||||
Dashboard → Combos → Neues erstellen
|
||||
|
||||
Name: premium-coding
|
||||
Modelle:
|
||||
1. cc/claude-opus-4-6 (Primäres Abo)
|
||||
2. glm/glm-4.7 (Günstiges Backup, $0.6/1M)
|
||||
3. minimax/MiniMax-M2.1 (Günstigster Fallback, $0.20/1M)
|
||||
|
||||
Im CLI nutzen: premium-coding
|
||||
```
|
||||
|
||||
### Beispiel 2: Nur Kostenlos (Null Kosten)
|
||||
|
||||
```
|
||||
Name: free-combo
|
||||
Modelle:
|
||||
1. gc/gemini-3-flash-preview (180K gratis/Monat)
|
||||
2. if/kimi-k2-thinking (unbegrenzt)
|
||||
3. qw/qwen3-coder-plus (unbegrenzt)
|
||||
|
||||
Kosten: Für immer $0!
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>🔧 CLI-Integration</b></summary>
|
||||
|
||||
### Cursor IDE
|
||||
|
||||
```
|
||||
Einstellungen → Modelle → Erweitert:
|
||||
OpenAI API Base URL: http://localhost:20128/v1
|
||||
OpenAI API Key: [aus OmniRoute Dashboard]
|
||||
Model: cc/claude-opus-4-6
|
||||
```
|
||||
|
||||
### Claude Code
|
||||
|
||||
Nutze die **CLI Tools** Seite im Dashboard für Ein-Klick-Konfiguration, oder bearbeite `~/.claude/settings.json` manuell.
|
||||
|
||||
### Codex CLI
|
||||
|
||||
```bash
|
||||
export OPENAI_BASE_URL="http://localhost:20128"
|
||||
export OPENAI_API_KEY="your-omniroute-api-key"
|
||||
|
||||
codex "your prompt"
|
||||
```
|
||||
|
||||
### OpenClaw
|
||||
|
||||
**Option 1 — Dashboard (empfohlen):**
|
||||
|
||||
```
|
||||
Dashboard → CLI Tools → OpenClaw → Modell wählen → Anwenden
|
||||
```
|
||||
|
||||
**Option 2 — Manuell:** `~/.openclaw/openclaw.json` bearbeiten:
|
||||
|
||||
```json
|
||||
{
|
||||
"models": {
|
||||
"providers": {
|
||||
"omniroute": {
|
||||
"baseUrl": "http://127.0.0.1:20128/v1",
|
||||
"apiKey": "sk_omniroute",
|
||||
"api": "openai-completions"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> **Hinweis:** OpenClaw funktioniert nur mit lokalem OmniRoute. Verwende `127.0.0.1` statt `localhost` um IPv6-Auflösungsprobleme zu vermeiden.
|
||||
|
||||
### Cline / Continue / RooCode
|
||||
|
||||
```
|
||||
Einstellungen → API-Konfiguration:
|
||||
Anbieter: OpenAI Compatible
|
||||
Base URL: http://localhost:20128/v1
|
||||
API Key: [aus OmniRoute Dashboard]
|
||||
Model: if/kimi-k2-thinking
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## 📊 Verfügbare Modelle
|
||||
|
||||
<details>
|
||||
<summary><b>Alle verfügbaren Modelle anzeigen</b></summary>
|
||||
|
||||
**Claude Code (`cc/`)** - Pro/Max:
|
||||
|
||||
- `cc/claude-opus-4-6`
|
||||
- `cc/claude-sonnet-4-5-20250929`
|
||||
- `cc/claude-haiku-4-5-20251001`
|
||||
|
||||
**Codex (`cx/`)** - Plus/Pro:
|
||||
|
||||
- `cx/gpt-5.2-codex`
|
||||
- `cx/gpt-5.1-codex-max`
|
||||
|
||||
**Gemini CLI (`gc/`)** - KOSTENLOS:
|
||||
|
||||
- `gc/gemini-3-flash-preview`
|
||||
- `gc/gemini-2.5-pro`
|
||||
|
||||
**GitHub Copilot (`gh/`)**:
|
||||
|
||||
- `gh/gpt-5`
|
||||
- `gh/claude-4.5-sonnet`
|
||||
|
||||
**NVIDIA NIM (`nvidia/`)** - KOSTENLOSE Credits:
|
||||
|
||||
- `nvidia/llama-3.3-70b-instruct`
|
||||
- `nvidia/mistral-7b-instruct`
|
||||
- 50+ weitere Modelle auf [build.nvidia.com](https://build.nvidia.com)
|
||||
|
||||
**GLM (`glm/`)** - $0.6/1M:
|
||||
|
||||
- `glm/glm-4.7`
|
||||
|
||||
**MiniMax (`minimax/`)** - $0.2/1M:
|
||||
|
||||
- `minimax/MiniMax-M2.1`
|
||||
|
||||
**iFlow (`if/`)** - KOSTENLOS:
|
||||
|
||||
- `if/kimi-k2-thinking`
|
||||
- `if/qwen3-coder-plus`
|
||||
- `if/deepseek-r1`
|
||||
- `if/glm-4.7`
|
||||
- `if/minimax-m2`
|
||||
|
||||
**Qwen (`qw/`)** - KOSTENLOS:
|
||||
|
||||
- `qw/qwen3-coder-plus`
|
||||
- `qw/qwen3-coder-flash`
|
||||
|
||||
**Kiro (`kr/`)** - KOSTENLOS:
|
||||
|
||||
- `kr/claude-sonnet-4.5`
|
||||
- `kr/claude-haiku-4.5`
|
||||
|
||||
**OpenRouter (`or/`)** - 100+ Modelle:
|
||||
|
||||
- `or/anthropic/claude-4-sonnet`
|
||||
- `or/google/gemini-2.5-pro`
|
||||
- Jedes Modell von [openrouter.ai/models](https://openrouter.ai/models)
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Evaluierungen (Evals)
|
||||
|
||||
OmniRoute enthält ein integriertes Evaluierungs-Framework zum Testen der LLM-Antwortqualität gegen ein Golden Set. Zugang über **Analytics → Evals** im Dashboard.
|
||||
|
||||
### Integriertes Golden Set
|
||||
|
||||
Das vorgeladene „OmniRoute Golden Set" enthält 10 Testfälle:
|
||||
|
||||
- Begrüßungen, Mathematik, Geographie, Code-Generierung
|
||||
- JSON-Formatkonformität, Übersetzung, Markdown
|
||||
- Sicherheitsablehnung (schädlicher Inhalt), Zählung, Boolesche Logik
|
||||
|
||||
### Evaluierungsstrategien
|
||||
|
||||
| Strategie | Beschreibung | Beispiel |
|
||||
| ---------- | ---------------------------------------------------------- | -------------------------------- |
|
||||
| `exact` | Ausgabe muss exakt übereinstimmen | `"4"` |
|
||||
| `contains` | Ausgabe muss Teilzeichenfolge enthalten (case-insensitive) | `"Paris"` |
|
||||
| `regex` | Ausgabe muss Regex-Muster entsprechen | `"1.*2.*3"` |
|
||||
| `custom` | Benutzerdefinierte JS-Funktion gibt true/false zurück | `(output) => output.length > 10` |
|
||||
|
||||
---
|
||||
|
||||
## 🐛 Fehlerbehebung
|
||||
|
||||
<details>
|
||||
<summary><b>Klicke zum Erweitern der Fehlerbehebungsanleitung</b></summary>
|
||||
|
||||
**„Language model did not provide messages"**
|
||||
|
||||
- Anbieter-Kontingent erschöpft → Kontingent-Tracker im Dashboard prüfen
|
||||
- Lösung: Combo mit Fallback nutzen oder zu günstigerer Stufe wechseln
|
||||
|
||||
**Rate Limiting**
|
||||
|
||||
- Abo-Kontingent erschöpft → Fallback zu GLM/MiniMax
|
||||
- Combo hinzufügen: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
|
||||
|
||||
**OAuth-Token abgelaufen**
|
||||
|
||||
- Wird automatisch von OmniRoute erneuert
|
||||
- Falls Problem bestehen bleibt: Dashboard → Anbieter → Neu verbinden
|
||||
|
||||
**Hohe Kosten**
|
||||
|
||||
- Nutzungsstatistiken unter Dashboard → Kosten prüfen
|
||||
- Primärmodell auf GLM/MiniMax umstellen
|
||||
- Gratis-Stufe (Gemini CLI, iFlow) für unkritische Aufgaben nutzen
|
||||
|
||||
**Dashboard öffnet sich auf falschem Port**
|
||||
|
||||
- `PORT=20128` und `NEXT_PUBLIC_BASE_URL=http://localhost:20128` setzen
|
||||
|
||||
**Cloud-Sync-Fehler**
|
||||
|
||||
- Prüfe dass `BASE_URL` auf deine laufende Instanz zeigt
|
||||
- Prüfe dass `CLOUD_URL` auf den erwarteten Cloud-Endpoint zeigt
|
||||
- `NEXT_PUBLIC_*` Werte mit Serverwerten synchron halten
|
||||
|
||||
**Erster Login funktioniert nicht**
|
||||
|
||||
- `INITIAL_PASSWORD` in `.env` prüfen
|
||||
- Falls nicht gesetzt, Standard-Passwort ist `123456`
|
||||
|
||||
**Keine Anfrage-Logs**
|
||||
|
||||
- `ENABLE_REQUEST_LOGS=true` in `.env` setzen
|
||||
|
||||
**Verbindungstest zeigt „Invalid" für OpenAI-kompatible Anbieter**
|
||||
|
||||
- Viele Anbieter stellen den `/models` Endpoint nicht bereit
|
||||
- OmniRoute v0.9.0+ enthält Fallback-Validierung via Chat Completions
|
||||
- Stelle sicher, dass die Base URL den `/v1` Suffix enthält
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Technologie-Stack
|
||||
|
||||
- **Runtime**: Node.js 20+
|
||||
- **Sprache**: TypeScript 5.9 — **100% TypeScript** in `src/` und `open-sse/` (v0.9.0)
|
||||
- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4
|
||||
- **Datenbank**: LowDB (JSON) + SQLite (Domain-Status + Proxy-Logs)
|
||||
- **Streaming**: Server-Sent Events (SSE)
|
||||
- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys
|
||||
- **Testing**: Node.js Test Runner (368+ Unit-Tests)
|
||||
- **CI/CD**: GitHub Actions (automatische npm + Docker Hub Veröffentlichung bei Release)
|
||||
- **Website**: [omniroute.online](https://omniroute.online)
|
||||
- **Paket**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)
|
||||
- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)
|
||||
- **Resilienz**: Circuit Breaker, exponentieller Backoff, Anti-Thundering Herd, TLS-Spoofing
|
||||
|
||||
---
|
||||
|
||||
## 📖 Dokumentation
|
||||
|
||||
| Dokument | Beschreibung |
|
||||
| ------------------------------------------ | ---------------------------------------------- |
|
||||
| [Benutzerhandbuch](docs/USER_GUIDE.md) | Anbieter, Combos, CLI-Integration, Deploy |
|
||||
| [API-Referenz](docs/API_REFERENCE.md) | Alle Endpoints mit Beispielen |
|
||||
| [Fehlerbehebung](docs/TROUBLESHOOTING.md) | Häufige Probleme und Lösungen |
|
||||
| [Architektur](docs/ARCHITECTURE.md) | Systemarchitektur und Interna |
|
||||
| [Mitwirken](CONTRIBUTING.md) | Entwicklungs-Setup und Richtlinien |
|
||||
| [OpenAPI-Spezifikation](docs/openapi.yaml) | OpenAPI 3.0 Spezifikation |
|
||||
| [Sicherheitsrichtlinie](SECURITY.md) | Schwachstellen melden und Sicherheitspraktiken |
|
||||
|
||||
---
|
||||
|
||||
## 📧 Support
|
||||
|
||||
- **Website**: [omniroute.online](https://omniroute.online)
|
||||
- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
|
||||
- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
|
||||
- **Originalprojekt**: [9router von decolua](https://github.com/decolua/9router)
|
||||
|
||||
---
|
||||
|
||||
## 👥 Mitwirkende
|
||||
|
||||
[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
|
||||
|
||||
### Wie du mitwirken kannst
|
||||
|
||||
1. Repository forken
|
||||
2. Feature-Branch erstellen (`git checkout -b feature/amazing-feature`)
|
||||
3. Änderungen committen (`git commit -m 'Add amazing feature'`)
|
||||
4. Branch pushen (`git push origin feature/amazing-feature`)
|
||||
5. Pull Request öffnen
|
||||
|
||||
Siehe [CONTRIBUTING.md](CONTRIBUTING.md) für detaillierte Richtlinien.
|
||||
|
||||
### Neue Version veröffentlichen
|
||||
|
||||
```bash
|
||||
# Release erstellen — npm-Veröffentlichung erfolgt automatisch
|
||||
gh release create v0.9.0 --title "v0.9.0" --generate-notes
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Star-Verlauf
|
||||
|
||||
<a href="https://star-history.com/#diegosouzapw/OmniRoute&Date">
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=diegosouzapw/OmniRoute&type=Date&theme=dark" />
|
||||
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=diegosouzapw/OmniRoute&type=Date" />
|
||||
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=diegosouzapw/OmniRoute&type=Date" />
|
||||
</picture>
|
||||
</a>
|
||||
|
||||
---
|
||||
|
||||
## 🙏 Danksagungen
|
||||
|
||||
Besonderer Dank an **[9router](https://github.com/decolua/9router)** von **[decolua](https://github.com/decolua)** — das Originalprojekt, das diesen Fork inspiriert hat. OmniRoute baut auf diesem unglaublichen Fundament auf mit zusätzlichen Funktionen, Multi-Modalen APIs und einem vollständigen TypeScript-Rewrite.
|
||||
|
||||
Besonderer Dank an **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — die ursprüngliche Go-Implementierung, die diese JavaScript-Portierung inspiriert hat.
|
||||
|
||||
---
|
||||
|
||||
## 📄 Lizenz
|
||||
|
||||
MIT-Lizenz — siehe [LICENSE](LICENSE) für Details.
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
<sub>Mit ❤️ gemacht für Entwickler, die 24/7 programmieren</sub>
|
||||
<br/>
|
||||
<sub><a href="https://omniroute.online">omniroute.online</a></sub>
|
||||
</div>
|
||||
995
README.es.md
Normal file
995
README.es.md
Normal file
@@ -0,0 +1,995 @@
|
||||
<div align="center">
|
||||
<img src="./images/omniroute.png" alt="OmniRoute Dashboard" width="800"/>
|
||||
|
||||
# 🚀 OmniRoute — El Gateway de IA Gratuito
|
||||
|
||||
### Nunca dejes de programar. Enrutamiento inteligente hacia **modelos de IA GRATUITOS y económicos** con fallback automático.
|
||||
|
||||
_Tu proxy de API universal — un endpoint, 36+ proveedores, cero tiempo de inactividad._
|
||||
|
||||
**Chat Completions • Embeddings • Generación de Imágenes • Audio • Reranking • 100% TypeScript**
|
||||
|
||||
---
|
||||
|
||||
### 🤖 Proveedor de IA Gratuito para tus agentes de programación favoritos
|
||||
|
||||
_Conecta cualquier IDE o herramienta CLI con IA a través de OmniRoute — gateway de API gratuito para programación ilimitada._
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/cline/cline">
|
||||
<img src="./public/providers/openclaw.png" alt="OpenClaw" width="48"/><br/>
|
||||
<b>OpenClaw</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 205K</sub>
|
||||
</td>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/HKUDS/nanobot">
|
||||
<img src="./public/providers/nanobot.png" alt="NanoBot" width="48"/><br/>
|
||||
<b>NanoBot</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 20.9K</sub>
|
||||
</td>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/sipeed/picoclaw">
|
||||
<img src="./public/providers/picoclaw.jpg" alt="PicoClaw" width="48"/><br/>
|
||||
<b>PicoClaw</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 14.6K</sub>
|
||||
</td>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/zeroclaw-labs/zeroclaw">
|
||||
<img src="./public/providers/zeroclaw.png" alt="ZeroClaw" width="48"/><br/>
|
||||
<b>ZeroClaw</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 9.9K</sub>
|
||||
</td>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/nearai/ironclaw">
|
||||
<img src="./public/providers/ironclaw.png" alt="IronClaw" width="48"/><br/>
|
||||
<b>IronClaw</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 2.1K</sub>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/anomalyco/opencode">
|
||||
<img src="./public/providers/opencode.svg" alt="OpenCode" width="48"/><br/>
|
||||
<b>OpenCode</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 106K</sub>
|
||||
</td>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/openai/codex">
|
||||
<img src="./public/providers/codex.png" alt="Codex CLI" width="48"/><br/>
|
||||
<b>Codex CLI</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 60.8K</sub>
|
||||
</td>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/anthropics/claude-code">
|
||||
<img src="./public/providers/claude.png" alt="Claude Code" width="48"/><br/>
|
||||
<b>Claude Code</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 67.3K</sub>
|
||||
</td>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/google-gemini/gemini-cli">
|
||||
<img src="./public/providers/gemini-cli.png" alt="Gemini CLI" width="48"/><br/>
|
||||
<b>Gemini CLI</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 94.7K</sub>
|
||||
</td>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/Kilo-Org/kilocode">
|
||||
<img src="./public/providers/kilocode.png" alt="Kilo Code" width="48"/><br/>
|
||||
<b>Kilo Code</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 15.5K</sub>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<sub>📡 Todos los agentes se conectan vía <code>http://localhost:20128/v1</code> o <code>http://cloud.omniroute.online/v1</code> — una configuración, modelos y cuota ilimitados</sub>
|
||||
|
||||
---
|
||||
|
||||
[](https://www.npmjs.com/package/omniroute)
|
||||
[](https://hub.docker.com/r/diegosouzapw/omniroute)
|
||||
[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
|
||||
[](https://omniroute.online)
|
||||
|
||||
[🌐 Website](https://omniroute.online) • [🚀 Inicio Rápido](#-inicio-rápido) • [💡 Características](#-características-principales) • [📖 Docs](#-documentación) • [💰 Precios](#-precios-resumidos)
|
||||
|
||||
🌐 **Disponible en:** [English](README.md) | [Português](README.pt-BR.md) | [Español](README.es.md) | [Русский](README.ru.md) | [中文](README.zh-CN.md) | [Deutsch](README.de.md) | [Français](README.fr.md) | [Italiano](README.it.md)
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## 🤔 ¿Por qué OmniRoute?
|
||||
|
||||
**Deja de desperdiciar dinero y chocar con límites:**
|
||||
|
||||
- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> La cuota de suscripción expira sin usar cada mes
|
||||
- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> Los límites de tasa te detienen en medio de la programación
|
||||
- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> APIs caras ($20-50/mes por proveedor)
|
||||
- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> Cambiar manualmente entre proveedores
|
||||
|
||||
**OmniRoute resuelve esto:**
|
||||
|
||||
- ✅ **Maximiza suscripciones** - Rastrea cuotas, usa cada bit antes del reset
|
||||
- ✅ **Fallback automático** - Suscripción → API Key → Barato → Gratuito, cero tiempo de inactividad
|
||||
- ✅ **Multi-cuenta** - Round-robin entre cuentas por proveedor
|
||||
- ✅ **Universal** - Funciona con Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, cualquier herramienta CLI
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Cómo Funciona
|
||||
|
||||
```
|
||||
┌─────────────┐
|
||||
│ Tu CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)
|
||||
│ Tool │
|
||||
└──────┬──────┘
|
||||
│ http://localhost:20128/v1
|
||||
↓
|
||||
┌─────────────────────────────────────────┐
|
||||
│ OmniRoute (Enrutador Inteligente) │
|
||||
│ • Traducción de formato (OpenAI ↔ Claude) │
|
||||
│ • Rastreo de cuota + Embeddings + Imágenes │
|
||||
│ • Renovación automática de tokens │
|
||||
└──────┬──────────────────────────────────┘
|
||||
│
|
||||
├─→ [Tier 1: SUSCRIPCIÓN] Claude Code, Codex, Gemini CLI
|
||||
│ ↓ cuota agotada
|
||||
├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.
|
||||
│ ↓ límite de presupuesto
|
||||
├─→ [Tier 3: BARATO] GLM ($0.6/1M), MiniMax ($0.2/1M)
|
||||
│ ↓ límite de presupuesto
|
||||
└─→ [Tier 4: GRATUITO] iFlow, Qwen, Kiro (ilimitado)
|
||||
|
||||
Resultado: Nunca dejes de programar, costo mínimo
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚡ Inicio Rápido
|
||||
|
||||
**1. Instala globalmente:**
|
||||
|
||||
```bash
|
||||
npm install -g omniroute
|
||||
omniroute
|
||||
```
|
||||
|
||||
🎉 El Dashboard se abre en `http://localhost:20128`
|
||||
|
||||
| Comando | Descripción |
|
||||
| ----------------------- | ---------------------------------------------- |
|
||||
| `omniroute` | Iniciar servidor (puerto predeterminado 20128) |
|
||||
| `omniroute --port 3000` | Usar puerto personalizado |
|
||||
| `omniroute --no-open` | No abrir navegador automáticamente |
|
||||
| `omniroute --help` | Mostrar ayuda |
|
||||
|
||||
**2. Conecta un proveedor GRATUITO:**
|
||||
|
||||
Dashboard → Proveedores → Conectar **Claude Code** o **Antigravity** → Login OAuth → ¡Listo!
|
||||
|
||||
**3. Usa en tu herramienta CLI:**
|
||||
|
||||
```
|
||||
Claude Code/Codex/Gemini CLI/OpenClaw/Cursor/Cline Configuración:
|
||||
Endpoint: http://localhost:20128/v1
|
||||
API Key: [copiar del dashboard]
|
||||
Model: if/kimi-k2-thinking
|
||||
```
|
||||
|
||||
**¡Eso es todo!** Comienza a programar con modelos de IA GRATUITOS.
|
||||
|
||||
**Alternativa — ejecutar desde código fuente:**
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
npm install
|
||||
PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🐳 Docker
|
||||
|
||||
OmniRoute está disponible como imagen Docker pública en [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
|
||||
|
||||
**Ejecución rápida:**
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
--name omniroute \
|
||||
--restart unless-stopped \
|
||||
-p 20128:20128 \
|
||||
-v omniroute-data:/app/data \
|
||||
diegosouzapw/omniroute:latest
|
||||
```
|
||||
|
||||
**Con archivo de entorno:**
|
||||
|
||||
```bash
|
||||
# Copia y edita el .env primero
|
||||
cp .env.example .env
|
||||
|
||||
docker run -d \
|
||||
--name omniroute \
|
||||
--restart unless-stopped \
|
||||
--env-file .env \
|
||||
-p 20128:20128 \
|
||||
-v omniroute-data:/app/data \
|
||||
diegosouzapw/omniroute:latest
|
||||
```
|
||||
|
||||
**Usando Docker Compose:**
|
||||
|
||||
```bash
|
||||
# Perfil base (sin herramientas CLI)
|
||||
docker compose --profile base up -d
|
||||
|
||||
# Perfil CLI (Claude Code, Codex, OpenClaw integrados)
|
||||
docker compose --profile cli up -d
|
||||
```
|
||||
|
||||
| Imagen | Tag | Tamaño | Descripción |
|
||||
| ------------------------ | -------- | ------ | ---------------------- |
|
||||
| `diegosouzapw/omniroute` | `latest` | ~250MB | Última versión estable |
|
||||
| `diegosouzapw/omniroute` | `0.9.0` | ~250MB | Versión actual |
|
||||
|
||||
---
|
||||
|
||||
## 💰 Precios Resumidos
|
||||
|
||||
| Tier | Proveedor | Costo | Reset de Cuota | Mejor Para |
|
||||
| ------------------ | ----------------- | ---------------------------- | ----------------- | ----------------------- |
|
||||
| **💳 SUSCRIPCIÓN** | Claude Code (Pro) | $20/mes | 5h + semanal | Ya suscrito |
|
||||
| | Codex (Plus/Pro) | $20-200/mes | 5h + semanal | Usuarios OpenAI |
|
||||
| | Gemini CLI | **GRATUITO** | 180K/mes + 1K/día | ¡Todos! |
|
||||
| | GitHub Copilot | $10-19/mes | Mensual | Usuarios GitHub |
|
||||
| **🔑 API KEY** | NVIDIA NIM | **GRATUITO** (1000 créditos) | Único | Pruebas gratuitas |
|
||||
| | DeepSeek | Por uso | Ninguno | Mejor precio/calidad |
|
||||
| | Groq | Tier gratuito + pago | Limitado | Inferencia ultra-rápida |
|
||||
| | xAI (Grok) | Por uso | Ninguno | Modelos Grok |
|
||||
| | Mistral | Tier gratuito + pago | Limitado | IA Europea |
|
||||
| | OpenRouter | Por uso | Ninguno | 100+ modelos |
|
||||
| **💰 BARATO** | GLM-4.7 | $0.6/1M | Diario 10h | Respaldo económico |
|
||||
| | MiniMax M2.1 | $0.2/1M | Rotativo 5h | Opción más barata |
|
||||
| | Kimi K2 | $9/mes fijo | 10M tokens/mes | Costo predecible |
|
||||
| **🆓 GRATUITO** | iFlow | $0 | Ilimitado | 8 modelos gratuitos |
|
||||
| | Qwen | $0 | Ilimitado | 3 modelos gratuitos |
|
||||
| | Kiro | $0 | Ilimitado | Claude gratuito |
|
||||
|
||||
**💡 Consejo Pro:** ¡Comienza con Gemini CLI (180K gratis/mes) + iFlow (ilimitado gratis) = $0 de costo!
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Casos de Uso
|
||||
|
||||
### Caso 1: "Tengo suscripción Claude Pro"
|
||||
|
||||
**Problema:** La cuota expira sin usar, límites de tasa durante programación intensa
|
||||
|
||||
```
|
||||
Combo: "maximize-claude"
|
||||
1. cc/claude-opus-4-6 (usar suscripción al máximo)
|
||||
2. glm/glm-4.7 (respaldo barato cuando la cuota se agota)
|
||||
3. if/kimi-k2-thinking (fallback de emergencia gratuito)
|
||||
|
||||
Costo mensual: $20 (suscripción) + ~$5 (respaldo) = $25 total
|
||||
vs. $20 + chocar con límites = frustración
|
||||
```
|
||||
|
||||
### Caso 2: "Quiero costo cero"
|
||||
|
||||
**Problema:** No puede pagar suscripciones, necesita IA confiable para programar
|
||||
|
||||
```
|
||||
Combo: "free-forever"
|
||||
1. gc/gemini-3-flash (180K gratis/mes)
|
||||
2. if/kimi-k2-thinking (ilimitado gratis)
|
||||
3. qw/qwen3-coder-plus (ilimitado gratis)
|
||||
|
||||
Costo mensual: $0
|
||||
Calidad: Modelos listos para producción
|
||||
```
|
||||
|
||||
### Caso 3: "Necesito programar 24/7, sin interrupciones"
|
||||
|
||||
**Problema:** Plazos ajustados, no puede permitirse tiempo de inactividad
|
||||
|
||||
```
|
||||
Combo: "always-on"
|
||||
1. cc/claude-opus-4-6 (mejor calidad)
|
||||
2. cx/gpt-5.2-codex (segunda suscripción)
|
||||
3. glm/glm-4.7 (barato, reset diario)
|
||||
4. minimax/MiniMax-M2.1 (más barato, reset 5h)
|
||||
5. if/kimi-k2-thinking (gratuito ilimitado)
|
||||
|
||||
Resultado: 5 capas de fallback = cero tiempo de inactividad
|
||||
```
|
||||
|
||||
### Caso 4: "Quiero IA GRATUITA en OpenClaw"
|
||||
|
||||
**Problema:** Necesita asistente de IA en apps de mensajería, completamente gratuito
|
||||
|
||||
```
|
||||
Combo: "openclaw-free"
|
||||
1. if/glm-4.7 (ilimitado gratis)
|
||||
2. if/minimax-m2.1 (ilimitado gratis)
|
||||
3. if/kimi-k2-thinking (ilimitado gratis)
|
||||
|
||||
Costo mensual: $0
|
||||
Acceso vía: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 💡 Características Principales
|
||||
|
||||
### 🧠 Enrutamiento e Inteligencia
|
||||
|
||||
| Característica | Qué Hace |
|
||||
| -------------------------------------- | ------------------------------------------------------------------------------- |
|
||||
| 🎯 **Fallback Inteligente 4 Tiers** | Auto-enrutamiento: Suscripción → API Key → Barato → Gratuito |
|
||||
| 📊 **Rastreo de Cuota en Tiempo Real** | Conteo de tokens en vivo + countdown de reset por proveedor |
|
||||
| 🔄 **Traducción de Formato** | OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro transparente |
|
||||
| 👥 **Soporte Multi-Cuenta** | Múltiples cuentas por proveedor con selección inteligente |
|
||||
| 🔄 **Renovación Automática de Token** | Tokens OAuth se renuevan automáticamente con reintentos |
|
||||
| 🎨 **Combos Personalizados** | 6 estrategias: fill-first, round-robin, p2c, random, least-used, cost-optimized |
|
||||
| 🧩 **Modelos Personalizados** | Agrega cualquier ID de modelo a cualquier proveedor |
|
||||
| 🌐 **Enrutador Wildcard** | Enruta patrones `provider/*` a cualquier proveedor dinámicamente |
|
||||
| 🧠 **Presupuesto de Razonamiento** | Modos passthrough, auto, custom y adaptativo para modelos de razonamiento |
|
||||
| 💬 **Inyección de System Prompt** | System prompt global aplicado en todas las solicitudes |
|
||||
| 📄 **API Responses** | Soporte completo de la API Responses de OpenAI (`/v1/responses`) para Codex |
|
||||
|
||||
### 🎵 APIs Multi-Modal
|
||||
|
||||
| Característica | Qué Hace |
|
||||
| ----------------------------- | ------------------------------------------------------ |
|
||||
| 🖼️ **Generación de Imágenes** | `/v1/images/generations` — 4 proveedores, 9+ modelos |
|
||||
| 📐 **Embeddings** | `/v1/embeddings` — 6 proveedores, 9+ modelos |
|
||||
| 🎤 **Transcripción de Audio** | `/v1/audio/transcriptions` — Compatible con Whisper |
|
||||
| 🔊 **Texto a Voz** | `/v1/audio/speech` — Síntesis de audio multi-proveedor |
|
||||
| 🛡️ **Moderaciones** | `/v1/moderations` — Verificaciones de seguridad |
|
||||
| 🔀 **Reranking** | `/v1/rerank` — Reranking de relevancia de documentos |
|
||||
|
||||
### 🛡️ Resiliencia y Seguridad
|
||||
|
||||
| Característica | Qué Hace |
|
||||
| ---------------------------------- | ---------------------------------------------------------------- |
|
||||
| 🔌 **Circuit Breaker** | Auto-apertura/cierre por proveedor con umbrales configurables |
|
||||
| 🛡️ **Anti-Thundering Herd** | Mutex + semáforo rate-limit para proveedores con API key |
|
||||
| 🧠 **Caché Semántico** | Caché de dos niveles (firma + semántico) reduce costo y latencia |
|
||||
| ⚡ **Idempotencia de Solicitud** | Ventana de dedup de 5s para solicitudes duplicadas |
|
||||
| 🔒 **Spoofing de Fingerprint TLS** | Bypass de detección de bot vía TLS con wreq-js |
|
||||
| 🌐 **Filtrado de IP** | Allowlist/blocklist para control de acceso a la API |
|
||||
| 📊 **Rate Limits Editables** | RPM, gap mínimo y concurrencia máxima configurables |
|
||||
|
||||
### 📊 Observabilidad y Analytics
|
||||
|
||||
| Característica | Qué Hace |
|
||||
| ------------------------------ | --------------------------------------------------------------------- |
|
||||
| 📝 **Logs de Solicitud** | Modo debug con logs completos de request/response |
|
||||
| 💾 **Logs SQLite** | Logs de proxy persistentes sobreviven a reinicios |
|
||||
| 📊 **Dashboard de Analytics** | Recharts: cards de estadísticas, gráfico de uso, tabla de proveedores |
|
||||
| 📈 **Rastreo de Progreso** | Eventos de progreso SSE opt-in para streaming |
|
||||
| 🧪 **Evaluaciones de LLM** | Pruebas con conjunto golden y 4 estrategias de match |
|
||||
| 🔍 **Telemetría de Solicitud** | Agregación de latencia p50/p95/p99 + rastreo X-Request-Id |
|
||||
| 📋 **Logs + Cuotas** | Páginas dedicadas para navegación de logs y rastreo de cuotas |
|
||||
| 🏥 **Dashboard de Salud** | Uptime, estados de circuit breaker, lockouts, stats de caché |
|
||||
| 💰 **Rastreo de Costos** | Gestión de presupuesto + configuración de precios por modelo |
|
||||
|
||||
### ☁️ Deploy y Sincronización
|
||||
|
||||
| Característica | Qué Hace |
|
||||
| --------------------------------- | ------------------------------------------------------------------------------- |
|
||||
| 💾 **Cloud Sync** | Sincroniza configuraciones entre dispositivos vía Cloudflare Workers |
|
||||
| 🌐 **Deploy en Cualquier Lugar** | Localhost, VPS, Docker, Cloudflare Workers |
|
||||
| 🔑 **Gestión de API Keys** | Genera, rota y define alcance de API keys por proveedor |
|
||||
| 🧙 **Asistente de Configuración** | Setup guiado en 4 pasos para nuevos usuarios |
|
||||
| 🔧 **Dashboard CLI Tools** | Configuración en un clic para Claude, Codex, Cline, OpenClaw, Kilo, Antigravity |
|
||||
| 🔄 **Backups de DB** | Backup y restauración automáticos de todas las configuraciones |
|
||||
|
||||
<details>
|
||||
<summary><b>📖 Detalles de Características</b></summary>
|
||||
|
||||
### 🎯 Fallback Inteligente 4 Tiers
|
||||
|
||||
Crea combos con fallback automático:
|
||||
|
||||
```
|
||||
Combo: "my-coding-stack"
|
||||
1. cc/claude-opus-4-6 (tu suscripción)
|
||||
2. nvidia/llama-3.3-70b (API NVIDIA gratuita)
|
||||
3. glm/glm-4.7 (respaldo barato, $0.6/1M)
|
||||
4. if/kimi-k2-thinking (fallback gratuito)
|
||||
|
||||
→ Cambia automáticamente cuando la cuota se agota o ocurren errores
|
||||
```
|
||||
|
||||
### 📊 Rastreo de Cuota en Tiempo Real
|
||||
|
||||
- Consumo de tokens por proveedor
|
||||
- Countdown de reset (5 horas, diario, semanal)
|
||||
- Estimación de costo para tiers pagos
|
||||
- Reportes de gastos mensuales
|
||||
|
||||
### 🔄 Traducción de Formato
|
||||
|
||||
Traducción transparente entre formatos:
|
||||
|
||||
- **OpenAI** ↔ **Claude** ↔ **Gemini** ↔ **OpenAI Responses**
|
||||
- Tu herramienta CLI envía formato OpenAI → OmniRoute traduce → El proveedor recibe formato nativo
|
||||
- Funciona con cualquier herramienta que soporte endpoints OpenAI personalizados
|
||||
|
||||
### 👥 Soporte Multi-Cuenta
|
||||
|
||||
- Agrega múltiples cuentas por proveedor
|
||||
- Round-robin automático o enrutamiento por prioridad
|
||||
- Fallback a la siguiente cuenta cuando una alcanza la cuota
|
||||
|
||||
### 🔄 Renovación Automática de Token
|
||||
|
||||
- Los tokens OAuth se renuevan automáticamente antes de expirar
|
||||
- Sin necesidad de re-autenticación manual
|
||||
- Experiencia transparente en todos los proveedores
|
||||
|
||||
### 🎨 Combos Personalizados
|
||||
|
||||
- Crea combinaciones ilimitadas de modelos
|
||||
- 6 estrategias: fill-first, round-robin, power-of-two-choices, random, least-used, cost-optimized
|
||||
- Comparte combos entre dispositivos con Cloud Sync
|
||||
|
||||
### 🏥 Dashboard de Salud
|
||||
|
||||
- Estado del sistema (uptime, versión, uso de memoria)
|
||||
- Estados de circuit breaker por proveedor (Closed/Open/Half-Open)
|
||||
- Estado de rate limit y lockouts activos
|
||||
- Estadísticas de caché de firma
|
||||
- Telemetría de latencia (p50/p95/p99) + caché de prompt
|
||||
- Reset de salud con un clic
|
||||
|
||||
### 🔧 Playground del Traductor
|
||||
|
||||
- Debug, prueba y visualiza traducciones de formato de API
|
||||
- Envía solicitudes y ve cómo OmniRoute traduce entre formatos de proveedores
|
||||
- Invaluable para troubleshooting de problemas de integración
|
||||
|
||||
### 💾 Cloud Sync
|
||||
|
||||
- Sincroniza proveedores, combos y configuraciones entre dispositivos
|
||||
- Sincronización automática en segundo plano
|
||||
- Almacenamiento cifrado seguro
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## 📖 Guía de Configuración
|
||||
|
||||
<details>
|
||||
<summary><b>💳 Proveedores por Suscripción</b></summary>
|
||||
|
||||
### Claude Code (Pro/Max)
|
||||
|
||||
```bash
|
||||
Dashboard → Proveedores → Conectar Claude Code
|
||||
→ Login OAuth → Renovación automática de token
|
||||
→ Rastreo de cuota 5h + semanal
|
||||
|
||||
Modelos:
|
||||
cc/claude-opus-4-6
|
||||
cc/claude-sonnet-4-5-20250929
|
||||
cc/claude-haiku-4-5-20251001
|
||||
```
|
||||
|
||||
**Consejo Pro:** Usa Opus para tareas complejas, Sonnet para velocidad. ¡OmniRoute rastrea cuota por modelo!
|
||||
|
||||
### OpenAI Codex (Plus/Pro)
|
||||
|
||||
```bash
|
||||
Dashboard → Proveedores → Conectar Codex
|
||||
→ Login OAuth (puerto 1455)
|
||||
→ Reset 5h + semanal
|
||||
|
||||
Modelos:
|
||||
cx/gpt-5.2-codex
|
||||
cx/gpt-5.1-codex-max
|
||||
```
|
||||
|
||||
### Gemini CLI (¡GRATUITO 180K/mes!)
|
||||
|
||||
```bash
|
||||
Dashboard → Proveedores → Conectar Gemini CLI
|
||||
→ Google OAuth
|
||||
→ 180K completions/mes + 1K/día
|
||||
|
||||
Modelos:
|
||||
gc/gemini-3-flash-preview
|
||||
gc/gemini-2.5-pro
|
||||
```
|
||||
|
||||
**Mejor Valor:** ¡Tier gratuito enorme! Úsalo antes de los tiers pagos.
|
||||
|
||||
### GitHub Copilot
|
||||
|
||||
```bash
|
||||
Dashboard → Proveedores → Conectar GitHub
|
||||
→ OAuth vía GitHub
|
||||
→ Reset mensual (1ro del mes)
|
||||
|
||||
Modelos:
|
||||
gh/gpt-5
|
||||
gh/claude-4.5-sonnet
|
||||
gh/gemini-3-pro
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>🔑 Proveedores por API Key</b></summary>
|
||||
|
||||
### NVIDIA NIM (¡GRATUITO 1000 créditos!)
|
||||
|
||||
1. Regístrate: [build.nvidia.com](https://build.nvidia.com)
|
||||
2. Obtén API key gratuita (1000 créditos de inferencia incluidos)
|
||||
3. Dashboard → Agregar Proveedor → NVIDIA NIM:
|
||||
- API Key: `nvapi-your-key`
|
||||
|
||||
**Modelos:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, y 50+ más
|
||||
|
||||
**Consejo Pro:** ¡API compatible con OpenAI — funciona perfectamente con la traducción de formato de OmniRoute!
|
||||
|
||||
### DeepSeek
|
||||
|
||||
1. Regístrate: [platform.deepseek.com](https://platform.deepseek.com)
|
||||
2. Obtén API key
|
||||
3. Dashboard → Agregar Proveedor → DeepSeek
|
||||
|
||||
**Modelos:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`
|
||||
|
||||
### Groq (¡Tier Gratuito Disponible!)
|
||||
|
||||
1. Regístrate: [console.groq.com](https://console.groq.com)
|
||||
2. Obtén API key (tier gratuito incluido)
|
||||
3. Dashboard → Agregar Proveedor → Groq
|
||||
|
||||
**Modelos:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`
|
||||
|
||||
**Consejo Pro:** ¡Inferencia ultra-rápida — mejor para programación en tiempo real!
|
||||
|
||||
### OpenRouter (100+ Modelos)
|
||||
|
||||
1. Regístrate: [openrouter.ai](https://openrouter.ai)
|
||||
2. Obtén API key
|
||||
3. Dashboard → Agregar Proveedor → OpenRouter
|
||||
|
||||
**Modelos:** Accede a 100+ modelos de todos los principales proveedores a través de una única API key.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>💰 Proveedores Baratos (Respaldo)</b></summary>
|
||||
|
||||
### GLM-4.7 (Reset diario, $0.6/1M)
|
||||
|
||||
1. Regístrate: [Zhipu AI](https://open.bigmodel.cn/)
|
||||
2. Obtén API key del Plan Coding
|
||||
3. Dashboard → Agregar API Key:
|
||||
- Proveedor: `glm`
|
||||
- API Key: `your-key`
|
||||
|
||||
**Usa:** `glm/glm-4.7`
|
||||
|
||||
**Consejo Pro:** ¡El Plan Coding ofrece 3× cuota a 1/7 del costo! Reset diario 10:00 AM.
|
||||
|
||||
### MiniMax M2.1 (Reset 5h, $0.20/1M)
|
||||
|
||||
1. Regístrate: [MiniMax](https://www.minimax.io/)
|
||||
2. Obtén API key
|
||||
3. Dashboard → Agregar API Key
|
||||
|
||||
**Usa:** `minimax/MiniMax-M2.1`
|
||||
|
||||
**Consejo Pro:** ¡Opción más barata para contexto largo (1M tokens)!
|
||||
|
||||
### Kimi K2 ($9/mes fijo)
|
||||
|
||||
1. Suscríbete: [Moonshot AI](https://platform.moonshot.ai/)
|
||||
2. Obtén API key
|
||||
3. Dashboard → Agregar API Key
|
||||
|
||||
**Usa:** `kimi/kimi-latest`
|
||||
|
||||
**Consejo Pro:** ¡$9/mes fijo por 10M tokens = $0.90/1M de costo efectivo!
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>🆓 Proveedores GRATUITOS (Respaldo de Emergencia)</b></summary>
|
||||
|
||||
### iFlow (8 modelos GRATUITOS)
|
||||
|
||||
```bash
|
||||
Dashboard → Conectar iFlow
|
||||
→ Login OAuth iFlow
|
||||
→ Uso ilimitado
|
||||
|
||||
Modelos:
|
||||
if/kimi-k2-thinking
|
||||
if/qwen3-coder-plus
|
||||
if/glm-4.7
|
||||
if/minimax-m2
|
||||
if/deepseek-r1
|
||||
```
|
||||
|
||||
### Qwen (3 modelos GRATUITOS)
|
||||
|
||||
```bash
|
||||
Dashboard → Conectar Qwen
|
||||
→ Autorización por código de dispositivo
|
||||
→ Uso ilimitado
|
||||
|
||||
Modelos:
|
||||
qw/qwen3-coder-plus
|
||||
qw/qwen3-coder-flash
|
||||
```
|
||||
|
||||
### Kiro (Claude GRATUITO)
|
||||
|
||||
```bash
|
||||
Dashboard → Conectar Kiro
|
||||
→ AWS Builder ID o Google/GitHub
|
||||
→ Uso ilimitado
|
||||
|
||||
Modelos:
|
||||
kr/claude-sonnet-4.5
|
||||
kr/claude-haiku-4.5
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>🎨 Crear Combos</b></summary>
|
||||
|
||||
### Ejemplo 1: Maximizar Suscripción → Respaldo Barato
|
||||
|
||||
```
|
||||
Dashboard → Combos → Crear Nuevo
|
||||
|
||||
Nombre: premium-coding
|
||||
Modelos:
|
||||
1. cc/claude-opus-4-6 (Suscripción primaria)
|
||||
2. glm/glm-4.7 (Respaldo barato, $0.6/1M)
|
||||
3. minimax/MiniMax-M2.1 (Fallback más barato, $0.20/1M)
|
||||
|
||||
Usa en CLI: premium-coding
|
||||
```
|
||||
|
||||
### Ejemplo 2: Solo Gratuito (Costo Cero)
|
||||
|
||||
```
|
||||
Nombre: free-combo
|
||||
Modelos:
|
||||
1. gc/gemini-3-flash-preview (180K gratis/mes)
|
||||
2. if/kimi-k2-thinking (ilimitado)
|
||||
3. qw/qwen3-coder-plus (ilimitado)
|
||||
|
||||
Costo: ¡$0 para siempre!
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>🔧 Integración CLI</b></summary>
|
||||
|
||||
### Cursor IDE
|
||||
|
||||
```
|
||||
Configuración → Modelos → Avanzado:
|
||||
OpenAI API Base URL: http://localhost:20128/v1
|
||||
OpenAI API Key: [del dashboard OmniRoute]
|
||||
Model: cc/claude-opus-4-6
|
||||
```
|
||||
|
||||
### Claude Code
|
||||
|
||||
Usa la página **CLI Tools** en el dashboard para configuración en un clic, o edita `~/.claude/settings.json` manualmente.
|
||||
|
||||
### Codex CLI
|
||||
|
||||
```bash
|
||||
export OPENAI_BASE_URL="http://localhost:20128"
|
||||
export OPENAI_API_KEY="your-omniroute-api-key"
|
||||
|
||||
codex "your prompt"
|
||||
```
|
||||
|
||||
### OpenClaw
|
||||
|
||||
**Opción 1 — Dashboard (recomendado):**
|
||||
|
||||
```
|
||||
Dashboard → CLI Tools → OpenClaw → Seleccionar Modelo → Aplicar
|
||||
```
|
||||
|
||||
**Opción 2 — Manual:** Edita `~/.openclaw/openclaw.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"models": {
|
||||
"providers": {
|
||||
"omniroute": {
|
||||
"baseUrl": "http://127.0.0.1:20128/v1",
|
||||
"apiKey": "sk_omniroute",
|
||||
"api": "openai-completions"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> **Nota:** OpenClaw solo funciona con OmniRoute local. Usa `127.0.0.1` en lugar de `localhost` para evitar problemas de resolución IPv6.
|
||||
|
||||
### Cline / Continue / RooCode
|
||||
|
||||
```
|
||||
Configuración → Configuración de API:
|
||||
Proveedor: OpenAI Compatible
|
||||
Base URL: http://localhost:20128/v1
|
||||
API Key: [del dashboard OmniRoute]
|
||||
Model: if/kimi-k2-thinking
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## 📊 Modelos Disponibles
|
||||
|
||||
<details>
|
||||
<summary><b>Ver todos los modelos disponibles</b></summary>
|
||||
|
||||
**Claude Code (`cc/`)** - Pro/Max:
|
||||
|
||||
- `cc/claude-opus-4-6`
|
||||
- `cc/claude-sonnet-4-5-20250929`
|
||||
- `cc/claude-haiku-4-5-20251001`
|
||||
|
||||
**Codex (`cx/`)** - Plus/Pro:
|
||||
|
||||
- `cx/gpt-5.2-codex`
|
||||
- `cx/gpt-5.1-codex-max`
|
||||
|
||||
**Gemini CLI (`gc/`)** - GRATUITO:
|
||||
|
||||
- `gc/gemini-3-flash-preview`
|
||||
- `gc/gemini-2.5-pro`
|
||||
|
||||
**GitHub Copilot (`gh/`)**:
|
||||
|
||||
- `gh/gpt-5`
|
||||
- `gh/claude-4.5-sonnet`
|
||||
|
||||
**NVIDIA NIM (`nvidia/`)** - Créditos GRATUITOS:
|
||||
|
||||
- `nvidia/llama-3.3-70b-instruct`
|
||||
- `nvidia/mistral-7b-instruct`
|
||||
- 50+ más modelos en [build.nvidia.com](https://build.nvidia.com)
|
||||
|
||||
**GLM (`glm/`)** - $0.6/1M:
|
||||
|
||||
- `glm/glm-4.7`
|
||||
|
||||
**MiniMax (`minimax/`)** - $0.2/1M:
|
||||
|
||||
- `minimax/MiniMax-M2.1`
|
||||
|
||||
**iFlow (`if/`)** - GRATUITO:
|
||||
|
||||
- `if/kimi-k2-thinking`
|
||||
- `if/qwen3-coder-plus`
|
||||
- `if/deepseek-r1`
|
||||
- `if/glm-4.7`
|
||||
- `if/minimax-m2`
|
||||
|
||||
**Qwen (`qw/`)** - GRATUITO:
|
||||
|
||||
- `qw/qwen3-coder-plus`
|
||||
- `qw/qwen3-coder-flash`
|
||||
|
||||
**Kiro (`kr/`)** - GRATUITO:
|
||||
|
||||
- `kr/claude-sonnet-4.5`
|
||||
- `kr/claude-haiku-4.5`
|
||||
|
||||
**OpenRouter (`or/`)** - 100+ modelos:
|
||||
|
||||
- `or/anthropic/claude-4-sonnet`
|
||||
- `or/google/gemini-2.5-pro`
|
||||
- Cualquier modelo de [openrouter.ai/models](https://openrouter.ai/models)
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Evaluaciones (Evals)
|
||||
|
||||
OmniRoute incluye un framework de evaluación integrado para probar la calidad de respuestas de LLM contra un conjunto golden. Accede vía **Analytics → Evals** en el dashboard.
|
||||
|
||||
### Conjunto Golden Integrado
|
||||
|
||||
El "OmniRoute Golden Set" precargado contiene 10 casos de prueba que cubren:
|
||||
|
||||
- Saludos, matemáticas, geografía, generación de código
|
||||
- Conformidad de formato JSON, traducción, markdown
|
||||
- Rechazo de seguridad (contenido dañino), conteo, lógica booleana
|
||||
|
||||
### Estrategias de Evaluación
|
||||
|
||||
| Estrategia | Descripción | Ejemplo |
|
||||
| ---------- | ---------------------------------------------------- | -------------------------------- |
|
||||
| `exact` | La salida debe coincidir exactamente | `"4"` |
|
||||
| `contains` | La salida debe contener subcadena (case-insensitive) | `"Paris"` |
|
||||
| `regex` | La salida debe coincidir con el patrón regex | `"1.*2.*3"` |
|
||||
| `custom` | Función JS personalizada retorna true/false | `(output) => output.length > 10` |
|
||||
|
||||
---
|
||||
|
||||
## 🐛 Solución de Problemas
|
||||
|
||||
<details>
|
||||
<summary><b>Haz clic para expandir la guía de solución de problemas</b></summary>
|
||||
|
||||
**"Language model did not provide messages"**
|
||||
|
||||
- Cuota del proveedor agotada → Verifica el rastreador de cuota en el dashboard
|
||||
- Solución: Usa combo con fallback o cambia a tier más barato
|
||||
|
||||
**Rate limiting**
|
||||
|
||||
- Cuota de suscripción agotada → Fallback a GLM/MiniMax
|
||||
- Agrega combo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
|
||||
|
||||
**Token OAuth expirado**
|
||||
|
||||
- Renovado automáticamente por OmniRoute
|
||||
- Si persiste: Dashboard → Proveedor → Reconectar
|
||||
|
||||
**Costos altos**
|
||||
|
||||
- Verifica estadísticas de uso en Dashboard → Costos
|
||||
- Cambia modelo primario a GLM/MiniMax
|
||||
- Usa tier gratuito (Gemini CLI, iFlow) para tareas no críticas
|
||||
|
||||
**Dashboard se abre en el puerto equivocado**
|
||||
|
||||
- Establece `PORT=20128` y `NEXT_PUBLIC_BASE_URL=http://localhost:20128`
|
||||
|
||||
**Errores de cloud sync**
|
||||
|
||||
- Verifica que `BASE_URL` apunte a tu instancia en ejecución
|
||||
- Verifica que `CLOUD_URL` apunte a tu endpoint cloud esperado
|
||||
- Mantén los valores `NEXT_PUBLIC_*` alineados con los valores del servidor
|
||||
|
||||
**Primer login no funciona**
|
||||
|
||||
- Verifica `INITIAL_PASSWORD` en `.env`
|
||||
- Si no está definido, la contraseña predeterminada es `123456`
|
||||
|
||||
**Sin logs de solicitud**
|
||||
|
||||
- Establece `ENABLE_REQUEST_LOGS=true` en `.env`
|
||||
|
||||
**Prueba de conexión muestra "Invalid" para proveedores compatibles con OpenAI**
|
||||
|
||||
- Muchos proveedores no exponen el endpoint `/models`
|
||||
- OmniRoute v0.9.0+ incluye validación vía chat completions como fallback
|
||||
- Asegúrate de que la URL base incluya el sufijo `/v1`
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Stack Tecnológico
|
||||
|
||||
- **Runtime**: Node.js 20+
|
||||
- **Lenguaje**: TypeScript 5.9 — **100% TypeScript** en `src/` y `open-sse/` (v0.9.0)
|
||||
- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4
|
||||
- **Base de Datos**: LowDB (JSON) + SQLite (estado del dominio + logs de proxy)
|
||||
- **Streaming**: Server-Sent Events (SSE)
|
||||
- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys
|
||||
- **Testing**: Node.js test runner (368+ tests unitarios)
|
||||
- **CI/CD**: GitHub Actions (publicación automática npm + Docker Hub en release)
|
||||
- **Website**: [omniroute.online](https://omniroute.online)
|
||||
- **Paquete**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)
|
||||
- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)
|
||||
- **Resiliencia**: Circuit breaker, backoff exponencial, anti-thundering herd, spoofing TLS
|
||||
|
||||
---
|
||||
|
||||
## 📖 Documentación
|
||||
|
||||
| Documento | Descripción |
|
||||
| ------------------------------------------------ | -------------------------------------------------- |
|
||||
| [Guía del Usuario](docs/USER_GUIDE.md) | Proveedores, combos, integración CLI, deploy |
|
||||
| [Referencia de API](docs/API_REFERENCE.md) | Todos los endpoints con ejemplos |
|
||||
| [Solución de Problemas](docs/TROUBLESHOOTING.md) | Problemas comunes y soluciones |
|
||||
| [Arquitectura](docs/ARCHITECTURE.md) | Arquitectura del sistema e internos |
|
||||
| [Contribuir](CONTRIBUTING.md) | Setup de desarrollo y directrices |
|
||||
| [Spec OpenAPI](docs/openapi.yaml) | Especificación OpenAPI 3.0 |
|
||||
| [Política de Seguridad](SECURITY.md) | Reportar vulnerabilidades y prácticas de seguridad |
|
||||
|
||||
---
|
||||
|
||||
## 📧 Soporte
|
||||
|
||||
- **Website**: [omniroute.online](https://omniroute.online)
|
||||
- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
|
||||
- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
|
||||
- **Proyecto Original**: [9router por decolua](https://github.com/decolua/9router)
|
||||
|
||||
---
|
||||
|
||||
## 👥 Contribuidores
|
||||
|
||||
[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
|
||||
|
||||
### Cómo Contribuir
|
||||
|
||||
1. Haz fork del repositorio
|
||||
2. Crea tu rama de funcionalidad (`git checkout -b feature/amazing-feature`)
|
||||
3. Haz commit de tus cambios (`git commit -m 'Add amazing feature'`)
|
||||
4. Haz push a la rama (`git push origin feature/amazing-feature`)
|
||||
5. Abre un Pull Request
|
||||
|
||||
Consulta [CONTRIBUTING.md](CONTRIBUTING.md) para directrices detalladas.
|
||||
|
||||
### Lanzar una Nueva Versión
|
||||
|
||||
```bash
|
||||
# Crea un release — la publicación en npm ocurre automáticamente
|
||||
gh release create v0.9.0 --title "v0.9.0" --generate-notes
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Historial de Stars
|
||||
|
||||
<a href="https://star-history.com/#diegosouzapw/OmniRoute&Date">
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=diegosouzapw/OmniRoute&type=Date&theme=dark" />
|
||||
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=diegosouzapw/OmniRoute&type=Date" />
|
||||
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=diegosouzapw/OmniRoute&type=Date" />
|
||||
</picture>
|
||||
</a>
|
||||
|
||||
---
|
||||
|
||||
## 🙏 Agradecimientos
|
||||
|
||||
Agradecimiento especial a **[9router](https://github.com/decolua/9router)** por **[decolua](https://github.com/decolua)** — el proyecto original que inspiró este fork. OmniRoute se construye sobre esa increíble base con características adicionales, APIs multi-modal y una reescritura completa en TypeScript.
|
||||
|
||||
Agradecimiento especial a **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — la implementación original en Go que inspiró esta adaptación a JavaScript.
|
||||
|
||||
---
|
||||
|
||||
## 📄 Licencia
|
||||
|
||||
Licencia MIT - consulta [LICENSE](LICENSE) para detalles.
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
<sub>Hecho con ❤️ para desarrolladores que programan 24/7</sub>
|
||||
<br/>
|
||||
<sub><a href="https://omniroute.online">omniroute.online</a></sub>
|
||||
</div>
|
||||
995
README.fr.md
Normal file
995
README.fr.md
Normal file
@@ -0,0 +1,995 @@
|
||||
<div align="center">
|
||||
<img src="./images/omniroute.png" alt="OmniRoute Dashboard" width="800"/>
|
||||
|
||||
# 🚀 OmniRoute — La Passerelle IA Gratuite
|
||||
|
||||
### N'arrêtez jamais de coder. Routage intelligent vers des **modèles IA GRATUITS et économiques** avec fallback automatique.
|
||||
|
||||
_Votre proxy API universel — un endpoint, 36+ fournisseurs, zéro temps d'arrêt._
|
||||
|
||||
**Chat Completions • Embeddings • Génération d'images • Audio • Reranking • 100% TypeScript**
|
||||
|
||||
---
|
||||
|
||||
### 🤖 Fournisseur IA gratuit pour vos agents de programmation préférés
|
||||
|
||||
_Connectez n'importe quel IDE ou outil CLI alimenté par l'IA via OmniRoute — passerelle API gratuite pour un codage illimité._
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/cline/cline">
|
||||
<img src="./public/providers/openclaw.png" alt="OpenClaw" width="48"/><br/>
|
||||
<b>OpenClaw</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 205K</sub>
|
||||
</td>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/HKUDS/nanobot">
|
||||
<img src="./public/providers/nanobot.png" alt="NanoBot" width="48"/><br/>
|
||||
<b>NanoBot</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 20.9K</sub>
|
||||
</td>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/sipeed/picoclaw">
|
||||
<img src="./public/providers/picoclaw.jpg" alt="PicoClaw" width="48"/><br/>
|
||||
<b>PicoClaw</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 14.6K</sub>
|
||||
</td>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/zeroclaw-labs/zeroclaw">
|
||||
<img src="./public/providers/zeroclaw.png" alt="ZeroClaw" width="48"/><br/>
|
||||
<b>ZeroClaw</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 9.9K</sub>
|
||||
</td>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/nearai/ironclaw">
|
||||
<img src="./public/providers/ironclaw.png" alt="IronClaw" width="48"/><br/>
|
||||
<b>IronClaw</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 2.1K</sub>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/anomalyco/opencode">
|
||||
<img src="./public/providers/opencode.svg" alt="OpenCode" width="48"/><br/>
|
||||
<b>OpenCode</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 106K</sub>
|
||||
</td>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/openai/codex">
|
||||
<img src="./public/providers/codex.png" alt="Codex CLI" width="48"/><br/>
|
||||
<b>Codex CLI</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 60.8K</sub>
|
||||
</td>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/anthropics/claude-code">
|
||||
<img src="./public/providers/claude.png" alt="Claude Code" width="48"/><br/>
|
||||
<b>Claude Code</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 67.3K</sub>
|
||||
</td>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/google-gemini/gemini-cli">
|
||||
<img src="./public/providers/gemini-cli.png" alt="Gemini CLI" width="48"/><br/>
|
||||
<b>Gemini CLI</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 94.7K</sub>
|
||||
</td>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/Kilo-Org/kilocode">
|
||||
<img src="./public/providers/kilocode.png" alt="Kilo Code" width="48"/><br/>
|
||||
<b>Kilo Code</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 15.5K</sub>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<sub>📡 Tous les agents se connectent via <code>http://localhost:20128/v1</code> ou <code>http://cloud.omniroute.online/v1</code> — une configuration, modèles et quota illimités</sub>
|
||||
|
||||
---
|
||||
|
||||
[](https://www.npmjs.com/package/omniroute)
|
||||
[](https://hub.docker.com/r/diegosouzapw/omniroute)
|
||||
[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
|
||||
[](https://omniroute.online)
|
||||
|
||||
[🌐 Site web](https://omniroute.online) • [🚀 Démarrage rapide](#-démarrage-rapide) • [💡 Fonctionnalités](#-fonctionnalités-principales) • [📖 Docs](#-documentation) • [💰 Tarifs](#-aperçu-des-tarifs)
|
||||
|
||||
🌐 **Disponible en :** [English](README.md) | [Português](README.pt-BR.md) | [Español](README.es.md) | [Русский](README.ru.md) | [中文](README.zh-CN.md) | [Deutsch](README.de.md) | [Français](README.fr.md) | [Italiano](README.it.md)
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## 🤔 Pourquoi OmniRoute ?
|
||||
|
||||
**Arrêtez de gaspiller de l'argent et de vous heurter aux limites :**
|
||||
|
||||
- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> Le quota d'abonnement expire inutilisé chaque mois
|
||||
- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> Les limites de débit vous arrêtent en plein codage
|
||||
- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> APIs coûteuses (20-50 $/mois par fournisseur)
|
||||
- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> Changement manuel entre fournisseurs
|
||||
|
||||
**OmniRoute résout ces problèmes :**
|
||||
|
||||
- ✅ **Maximisez les abonnements** — Suivez les quotas, utilisez chaque bit avant la réinitialisation
|
||||
- ✅ **Fallback automatique** — Abonnement → Clé API → Économique → Gratuit, zéro temps d'arrêt
|
||||
- ✅ **Multi-comptes** — Round-robin entre les comptes par fournisseur
|
||||
- ✅ **Universel** — Fonctionne avec Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, tout outil CLI
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Comment ça fonctionne
|
||||
|
||||
```
|
||||
┌─────────────┐
|
||||
│ Votre CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)
|
||||
│ Tool │
|
||||
└──────┬──────┘
|
||||
│ http://localhost:20128/v1
|
||||
↓
|
||||
┌─────────────────────────────────────────┐
|
||||
│ OmniRoute (Routeur intelligent) │
|
||||
│ • Traduction de format (OpenAI ↔ Claude) │
|
||||
│ • Suivi des quotas + Embeddings + Images │
|
||||
│ • Renouvellement automatique des tokens │
|
||||
└──────┬──────────────────────────────────┘
|
||||
│
|
||||
├─→ [Tier 1: ABONNEMENT] Claude Code, Codex, Gemini CLI
|
||||
│ ↓ quota épuisé
|
||||
├─→ [Tier 2: CLÉ API] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.
|
||||
│ ↓ limite de budget
|
||||
├─→ [Tier 3: ÉCONOMIQUE] GLM ($0.6/1M), MiniMax ($0.2/1M)
|
||||
│ ↓ limite de budget
|
||||
└─→ [Tier 4: GRATUIT] iFlow, Qwen, Kiro (illimité)
|
||||
|
||||
Résultat : Ne jamais arrêter de coder, coût minimal
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚡ Démarrage rapide
|
||||
|
||||
**1. Installer globalement :**
|
||||
|
||||
```bash
|
||||
npm install -g omniroute
|
||||
omniroute
|
||||
```
|
||||
|
||||
🎉 Le tableau de bord s'ouvre sur `http://localhost:20128`
|
||||
|
||||
| Commande | Description |
|
||||
| ----------------------- | ------------------------------------------- |
|
||||
| `omniroute` | Démarrer le serveur (port par défaut 20128) |
|
||||
| `omniroute --port 3000` | Utiliser un port personnalisé |
|
||||
| `omniroute --no-open` | Ne pas ouvrir le navigateur automatiquement |
|
||||
| `omniroute --help` | Afficher l'aide |
|
||||
|
||||
**2. Connecter un fournisseur GRATUIT :**
|
||||
|
||||
Tableau de bord → Fournisseurs → Connecter **Claude Code** ou **Antigravity** → Connexion OAuth → Terminé !
|
||||
|
||||
**3. Utiliser dans votre outil CLI :**
|
||||
|
||||
```
|
||||
Claude Code/Codex/Gemini CLI/OpenClaw/Cursor/Cline Paramètres :
|
||||
Endpoint : http://localhost:20128/v1
|
||||
API Key : [copier depuis le tableau de bord]
|
||||
Model : if/kimi-k2-thinking
|
||||
```
|
||||
|
||||
**C'est tout !** Commencez à coder avec des modèles IA GRATUITS.
|
||||
|
||||
**Alternative — exécuter depuis le code source :**
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
npm install
|
||||
PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🐳 Docker
|
||||
|
||||
OmniRoute est disponible en tant qu'image Docker publique sur [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
|
||||
|
||||
**Démarrage rapide :**
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
--name omniroute \
|
||||
--restart unless-stopped \
|
||||
-p 20128:20128 \
|
||||
-v omniroute-data:/app/data \
|
||||
diegosouzapw/omniroute:latest
|
||||
```
|
||||
|
||||
**Avec fichier d'environnement :**
|
||||
|
||||
```bash
|
||||
# Copier et modifier le .env d'abord
|
||||
cp .env.example .env
|
||||
|
||||
docker run -d \
|
||||
--name omniroute \
|
||||
--restart unless-stopped \
|
||||
--env-file .env \
|
||||
-p 20128:20128 \
|
||||
-v omniroute-data:/app/data \
|
||||
diegosouzapw/omniroute:latest
|
||||
```
|
||||
|
||||
**Avec Docker Compose :**
|
||||
|
||||
```bash
|
||||
# Profil de base (sans outils CLI)
|
||||
docker compose --profile base up -d
|
||||
|
||||
# Profil CLI (Claude Code, Codex, OpenClaw intégrés)
|
||||
docker compose --profile cli up -d
|
||||
```
|
||||
|
||||
| Image | Tag | Taille | Description |
|
||||
| ------------------------ | -------- | ------ | ----------------------- |
|
||||
| `diegosouzapw/omniroute` | `latest` | ~250MB | Dernière version stable |
|
||||
| `diegosouzapw/omniroute` | `0.9.0` | ~250MB | Version actuelle |
|
||||
|
||||
---
|
||||
|
||||
## 💰 Aperçu des tarifs
|
||||
|
||||
| Tier | Fournisseur | Coût | Réinitialisation | Idéal pour |
|
||||
| ----------------- | ----------------- | -------------------------- | ------------------- | ----------------------------- |
|
||||
| **💳 ABONNEMENT** | Claude Code (Pro) | 20 $/mois | 5h + hebdomadaire | Déjà abonné |
|
||||
| | Codex (Plus/Pro) | 20-200 $/mois | 5h + hebdomadaire | Utilisateurs OpenAI |
|
||||
| | Gemini CLI | **GRATUIT** | 180K/mois + 1K/jour | Tout le monde ! |
|
||||
| | GitHub Copilot | 10-19 $/mois | Mensuel | Utilisateurs GitHub |
|
||||
| **🔑 CLÉ API** | NVIDIA NIM | **GRATUIT** (1000 crédits) | Unique | Tests gratuits |
|
||||
| | DeepSeek | À l'usage | Aucune | Meilleur rapport qualité-prix |
|
||||
| | Groq | Niveau gratuit + payant | Limité | Inférence ultra-rapide |
|
||||
| | xAI (Grok) | À l'usage | Aucune | Modèles Grok |
|
||||
| | Mistral | Niveau gratuit + payant | Limité | IA européenne |
|
||||
| | OpenRouter | À l'usage | Aucune | 100+ modèles |
|
||||
| **💰 ÉCONOMIQUE** | GLM-4.7 | 0,6 $/1M | Quotidien 10h | Backup économique |
|
||||
| | MiniMax M2.1 | 0,2 $/1M | Rotatif 5h | Option la moins chère |
|
||||
| | Kimi K2 | 9 $/mois fixe | 10M tokens/mois | Coût prévisible |
|
||||
| **🆓 GRATUIT** | iFlow | 0 $ | Illimité | 8 modèles gratuits |
|
||||
| | Qwen | 0 $ | Illimité | 3 modèles gratuits |
|
||||
| | Kiro | 0 $ | Illimité | Claude gratuit |
|
||||
|
||||
**💡 Conseil Pro :** Commencez avec Gemini CLI (180K gratuits/mois) + iFlow (illimité gratuit) = 0 $ de coût !
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Cas d'utilisation
|
||||
|
||||
### Cas 1 : « J'ai un abonnement Claude Pro »
|
||||
|
||||
**Problème :** Le quota expire inutilisé, limites de débit pendant le codage intensif
|
||||
|
||||
```
|
||||
Combo : "maximize-claude"
|
||||
1. cc/claude-opus-4-6 (utiliser l'abonnement au maximum)
|
||||
2. glm/glm-4.7 (backup économique quand le quota est épuisé)
|
||||
3. if/kimi-k2-thinking (fallback d'urgence gratuit)
|
||||
|
||||
Coût mensuel : 20 $ (abonnement) + ~5 $ (backup) = 25 $ au total
|
||||
vs. 20 $ + atteindre les limites = frustration
|
||||
```
|
||||
|
||||
### Cas 2 : « Je veux zéro coût »
|
||||
|
||||
**Problème :** Impossible de payer des abonnements, besoin d'IA fiable pour coder
|
||||
|
||||
```
|
||||
Combo : "free-forever"
|
||||
1. gc/gemini-3-flash (180K gratuits/mois)
|
||||
2. if/kimi-k2-thinking (illimité gratuit)
|
||||
3. qw/qwen3-coder-plus (illimité gratuit)
|
||||
|
||||
Coût mensuel : 0 $
|
||||
Qualité : Modèles prêts pour la production
|
||||
```
|
||||
|
||||
### Cas 3 : « Je dois coder 24/7, sans interruption »
|
||||
|
||||
**Problème :** Délais serrés, ne peut pas se permettre de temps d'arrêt
|
||||
|
||||
```
|
||||
Combo : "always-on"
|
||||
1. cc/claude-opus-4-6 (meilleure qualité)
|
||||
2. cx/gpt-5.2-codex (deuxième abonnement)
|
||||
3. glm/glm-4.7 (économique, reset quotidien)
|
||||
4. minimax/MiniMax-M2.1 (le moins cher, reset 5h)
|
||||
5. if/kimi-k2-thinking (gratuit illimité)
|
||||
|
||||
Résultat : 5 niveaux de fallback = zéro temps d'arrêt
|
||||
```
|
||||
|
||||
### Cas 4 : « Je veux l'IA GRATUITE dans OpenClaw »
|
||||
|
||||
**Problème :** Besoin d'assistant IA dans les apps de messagerie, entièrement gratuit
|
||||
|
||||
```
|
||||
Combo : "openclaw-free"
|
||||
1. if/glm-4.7 (illimité gratuit)
|
||||
2. if/minimax-m2.1 (illimité gratuit)
|
||||
3. if/kimi-k2-thinking (illimité gratuit)
|
||||
|
||||
Coût mensuel : 0 $
|
||||
Accès via : WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 💡 Fonctionnalités principales
|
||||
|
||||
### 🧠 Routage & Intelligence
|
||||
|
||||
| Fonctionnalité | Ce qu'elle fait |
|
||||
| ------------------------------------- | ------------------------------------------------------------------------------- |
|
||||
| 🎯 **Fallback intelligent 4 niveaux** | Auto-routage : Abonnement → Clé API → Économique → Gratuit |
|
||||
| 📊 **Suivi des quotas en temps réel** | Comptage de tokens en direct + compte à rebours de réinitialisation |
|
||||
| 🔄 **Traduction de format** | OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro transparent |
|
||||
| 👥 **Support multi-comptes** | Plusieurs comptes par fournisseur avec sélection intelligente |
|
||||
| 🔄 **Renouvellement auto des tokens** | Les tokens OAuth se renouvellent automatiquement avec retry |
|
||||
| 🎨 **Combos personnalisés** | 6 stratégies : fill-first, round-robin, p2c, random, least-used, cost-optimized |
|
||||
| 🧩 **Modèles personnalisés** | Ajoutez n'importe quel ID de modèle à n'importe quel fournisseur |
|
||||
| 🌐 **Routeur wildcard** | Routez les patterns `provider/*` vers n'importe quel fournisseur dynamiquement |
|
||||
| 🧠 **Budget de raisonnement** | Modes passthrough, auto, custom et adaptive pour les modèles de raisonnement |
|
||||
| 💬 **Injection System Prompt** | System prompt global appliqué à toutes les requêtes |
|
||||
| 📄 **API Responses** | Support complet de l'API Responses d'OpenAI (`/v1/responses`) pour Codex |
|
||||
|
||||
### 🎵 APIs multi-modales
|
||||
|
||||
| Fonctionnalité | Ce qu'elle fait |
|
||||
| -------------------------- | ------------------------------------------------------- |
|
||||
| 🖼️ **Génération d'images** | `/v1/images/generations` — 4 fournisseurs, 9+ modèles |
|
||||
| 📐 **Embeddings** | `/v1/embeddings` — 6 fournisseurs, 9+ modèles |
|
||||
| 🎤 **Transcription audio** | `/v1/audio/transcriptions` — compatible Whisper |
|
||||
| 🔊 **Texte vers parole** | `/v1/audio/speech` — synthèse audio multi-fournisseur |
|
||||
| 🛡️ **Modérations** | `/v1/moderations` — vérifications de sécurité |
|
||||
| 🔀 **Reranking** | `/v1/rerank` — reclassement de pertinence des documents |
|
||||
|
||||
### 🛡️ Résilience & Sécurité
|
||||
|
||||
| Fonctionnalité | Ce qu'elle fait |
|
||||
| ------------------------------- | -------------------------------------------------------------------- |
|
||||
| 🔌 **Circuit Breaker** | Ouverture/fermeture auto par fournisseur avec seuils configurables |
|
||||
| 🛡️ **Anti-Thundering Herd** | Mutex + sémaphore de rate-limit pour les fournisseurs avec clé API |
|
||||
| 🧠 **Cache sémantique** | Cache à deux niveaux (signature + sémantique) réduit coût et latence |
|
||||
| ⚡ **Idempotence des requêtes** | Fenêtre de dédup 5s pour les requêtes dupliquées |
|
||||
| 🔒 **Spoofing TLS Fingerprint** | Contournement de détection de bot via wreq-js |
|
||||
| 🌐 **Filtrage IP** | Allowlist/blocklist pour le contrôle d'accès API |
|
||||
| 📊 **Rate limits éditables** | RPM configurable, intervalle minimum, concurrence max |
|
||||
|
||||
### 📊 Observabilité & Analytique
|
||||
|
||||
| Fonctionnalité | Ce qu'elle fait |
|
||||
| --------------------------------- | ------------------------------------------------------------------------- |
|
||||
| 📝 **Logs de requêtes** | Mode debug avec logs complets requête/réponse |
|
||||
| 💾 **Logs SQLite** | Logs proxy persistants survivant aux redémarrages |
|
||||
| 📊 **Tableau de bord analytique** | Recharts : cartes de stats, graphique d'utilisation, tableau fournisseurs |
|
||||
| 📈 **Suivi de progression** | Événements SSE de progression opt-in pour le streaming |
|
||||
| 🧪 **Évaluations LLM** | Tests avec golden set et 4 stratégies de correspondance |
|
||||
| 🔍 **Télémétrie des requêtes** | Agrégation de latence p50/p95/p99 + traçage X-Request-Id |
|
||||
| 📋 **Logs + Quotas** | Pages dédiées pour navigation des logs et suivi des quotas |
|
||||
| 🏥 **Tableau de bord santé** | Uptime, états circuit breaker, lockouts, stats cache |
|
||||
| 💰 **Suivi des coûts** | Gestion de budget + configuration des prix par modèle |
|
||||
|
||||
### ☁️ Déploiement & Synchronisation
|
||||
|
||||
| Fonctionnalité | Ce qu'elle fait |
|
||||
| --------------------------------- | ------------------------------------------------------------------------------- |
|
||||
| 💾 **Cloud Sync** | Synchroniser les paramètres entre appareils via Cloudflare Workers |
|
||||
| 🌐 **Déployer partout** | Localhost, VPS, Docker, Cloudflare Workers |
|
||||
| 🔑 **Gestion des clés API** | Générer, faire tourner et limiter les clés API par fournisseur |
|
||||
| 🧙 **Assistant de configuration** | Setup guidé en 4 étapes pour les nouveaux utilisateurs |
|
||||
| 🔧 **Tableau de bord CLI Tools** | Configuration en un clic pour Claude, Codex, Cline, OpenClaw, Kilo, Antigravity |
|
||||
| 🔄 **Sauvegardes DB** | Sauvegarde et restauration automatiques de tous les paramètres |
|
||||
|
||||
<details>
|
||||
<summary><b>📖 Détails des fonctionnalités</b></summary>
|
||||
|
||||
### 🎯 Fallback intelligent 4 niveaux
|
||||
|
||||
Créez des combos avec fallback automatique :
|
||||
|
||||
```
|
||||
Combo : "my-coding-stack"
|
||||
1. cc/claude-opus-4-6 (votre abonnement)
|
||||
2. nvidia/llama-3.3-70b (API NVIDIA gratuite)
|
||||
3. glm/glm-4.7 (backup économique, $0.6/1M)
|
||||
4. if/kimi-k2-thinking (fallback gratuit)
|
||||
|
||||
→ Bascule automatiquement lorsque le quota est épuisé ou en cas d'erreurs
|
||||
```
|
||||
|
||||
### 📊 Suivi des quotas en temps réel
|
||||
|
||||
- Consommation de tokens par fournisseur
|
||||
- Compte à rebours de réinitialisation (5 heures, quotidien, hebdomadaire)
|
||||
- Estimation des coûts pour les niveaux payants
|
||||
- Rapports de dépenses mensuels
|
||||
|
||||
### 🔄 Traduction de format
|
||||
|
||||
Traduction transparente entre les formats :
|
||||
|
||||
- **OpenAI** ↔ **Claude** ↔ **Gemini** ↔ **OpenAI Responses**
|
||||
- Votre CLI envoie le format OpenAI → OmniRoute traduit → Le fournisseur reçoit le format natif
|
||||
- Fonctionne avec tout outil supportant les endpoints OpenAI personnalisés
|
||||
|
||||
### 👥 Support multi-comptes
|
||||
|
||||
- Ajouter plusieurs comptes par fournisseur
|
||||
- Round-robin automatique ou routage par priorité
|
||||
- Basculement vers le compte suivant lorsqu'un quota est atteint
|
||||
|
||||
### 🔄 Renouvellement automatique des tokens
|
||||
|
||||
- Les tokens OAuth se renouvellent automatiquement avant expiration
|
||||
- Pas de réauthentification manuelle nécessaire
|
||||
- Expérience transparente sur tous les fournisseurs
|
||||
|
||||
### 🎨 Combos personnalisés
|
||||
|
||||
- Créer des combinaisons de modèles illimitées
|
||||
- 6 stratégies : fill-first, round-robin, power-of-two-choices, random, least-used, cost-optimized
|
||||
- Partager les combos entre appareils avec Cloud Sync
|
||||
|
||||
### 🏥 Tableau de bord santé
|
||||
|
||||
- Statut du système (uptime, version, utilisation mémoire)
|
||||
- États des circuit breakers par fournisseur (Closed/Open/Half-Open)
|
||||
- Statut des rate limits et lockouts actifs
|
||||
- Statistiques du cache de signatures
|
||||
- Télémétrie de latence (p50/p95/p99) + cache de prompt
|
||||
- Réinitialisation de la santé en un clic
|
||||
|
||||
### 🔧 Playground du traducteur
|
||||
|
||||
- Déboguer, tester et visualiser les traductions de format d'API
|
||||
- Envoyer des requêtes et voir comment OmniRoute traduit entre les formats des fournisseurs
|
||||
- Inestimable pour résoudre les problèmes d'intégration
|
||||
|
||||
### 💾 Cloud Sync
|
||||
|
||||
- Synchroniser fournisseurs, combos et paramètres entre appareils
|
||||
- Synchronisation en arrière-plan automatique
|
||||
- Stockage chiffré sécurisé
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## 📖 Guide de configuration
|
||||
|
||||
<details>
|
||||
<summary><b>💳 Fournisseurs par abonnement</b></summary>
|
||||
|
||||
### Claude Code (Pro/Max)
|
||||
|
||||
```bash
|
||||
Tableau de bord → Fournisseurs → Connecter Claude Code
|
||||
→ Connexion OAuth → Renouvellement auto des tokens
|
||||
→ Suivi de quota 5h + hebdomadaire
|
||||
|
||||
Modèles :
|
||||
cc/claude-opus-4-6
|
||||
cc/claude-sonnet-4-5-20250929
|
||||
cc/claude-haiku-4-5-20251001
|
||||
```
|
||||
|
||||
**Conseil Pro :** Utilisez Opus pour les tâches complexes, Sonnet pour la vitesse. OmniRoute suit les quotas par modèle !
|
||||
|
||||
### OpenAI Codex (Plus/Pro)
|
||||
|
||||
```bash
|
||||
Tableau de bord → Fournisseurs → Connecter Codex
|
||||
→ Connexion OAuth (port 1455)
|
||||
→ Reset 5h + hebdomadaire
|
||||
|
||||
Modèles :
|
||||
cx/gpt-5.2-codex
|
||||
cx/gpt-5.1-codex-max
|
||||
```
|
||||
|
||||
### Gemini CLI (GRATUIT 180K/mois !)
|
||||
|
||||
```bash
|
||||
Tableau de bord → Fournisseurs → Connecter Gemini CLI
|
||||
→ Google OAuth
|
||||
→ 180K completions/mois + 1K/jour
|
||||
|
||||
Modèles :
|
||||
gc/gemini-3-flash-preview
|
||||
gc/gemini-2.5-pro
|
||||
```
|
||||
|
||||
**Meilleure valeur :** Niveau gratuit énorme ! Utilisez avant les niveaux payants.
|
||||
|
||||
### GitHub Copilot
|
||||
|
||||
```bash
|
||||
Tableau de bord → Fournisseurs → Connecter GitHub
|
||||
→ OAuth via GitHub
|
||||
→ Reset mensuel (1er du mois)
|
||||
|
||||
Modèles :
|
||||
gh/gpt-5
|
||||
gh/claude-4.5-sonnet
|
||||
gh/gemini-3-pro
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>🔑 Fournisseurs par clé API</b></summary>
|
||||
|
||||
### NVIDIA NIM (GRATUIT 1000 crédits !)
|
||||
|
||||
1. S'inscrire : [build.nvidia.com](https://build.nvidia.com)
|
||||
2. Obtenir une clé API gratuite (1000 crédits d'inférence inclus)
|
||||
3. Tableau de bord → Ajouter fournisseur → NVIDIA NIM :
|
||||
- API Key : `nvapi-your-key`
|
||||
|
||||
**Modèles :** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct` et 50+ autres
|
||||
|
||||
**Conseil Pro :** API compatible OpenAI — fonctionne parfaitement avec la traduction de format d'OmniRoute !
|
||||
|
||||
### DeepSeek
|
||||
|
||||
1. S'inscrire : [platform.deepseek.com](https://platform.deepseek.com)
|
||||
2. Obtenir une clé API
|
||||
3. Tableau de bord → Ajouter fournisseur → DeepSeek
|
||||
|
||||
**Modèles :** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`
|
||||
|
||||
### Groq (Niveau gratuit disponible !)
|
||||
|
||||
1. S'inscrire : [console.groq.com](https://console.groq.com)
|
||||
2. Obtenir une clé API (niveau gratuit inclus)
|
||||
3. Tableau de bord → Ajouter fournisseur → Groq
|
||||
|
||||
**Modèles :** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`
|
||||
|
||||
**Conseil Pro :** Inférence ultra-rapide — idéal pour le codage en temps réel !
|
||||
|
||||
### OpenRouter (100+ modèles)
|
||||
|
||||
1. S'inscrire : [openrouter.ai](https://openrouter.ai)
|
||||
2. Obtenir une clé API
|
||||
3. Tableau de bord → Ajouter fournisseur → OpenRouter
|
||||
|
||||
**Modèles :** Accès à 100+ modèles de tous les grands fournisseurs via une seule clé API.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>💰 Fournisseurs économiques (Backup)</b></summary>
|
||||
|
||||
### GLM-4.7 (Reset quotidien, $0.6/1M)
|
||||
|
||||
1. S'inscrire : [Zhipu AI](https://open.bigmodel.cn/)
|
||||
2. Obtenir une clé API du Coding Plan
|
||||
3. Tableau de bord → Ajouter clé API :
|
||||
- Fournisseur : `glm`
|
||||
- API Key : `your-key`
|
||||
|
||||
**Utilisez :** `glm/glm-4.7`
|
||||
|
||||
**Conseil Pro :** Le Coding Plan offre 3× le quota à 1/7 du coût ! Reset quotidien à 10h.
|
||||
|
||||
### MiniMax M2.1 (Reset 5h, $0.20/1M)
|
||||
|
||||
1. S'inscrire : [MiniMax](https://www.minimax.io/)
|
||||
2. Obtenir une clé API
|
||||
3. Tableau de bord → Ajouter clé API
|
||||
|
||||
**Utilisez :** `minimax/MiniMax-M2.1`
|
||||
|
||||
**Conseil Pro :** L'option la moins chère pour le contexte long (1M tokens) !
|
||||
|
||||
### Kimi K2 (9 $/mois fixe)
|
||||
|
||||
1. S'abonner : [Moonshot AI](https://platform.moonshot.ai/)
|
||||
2. Obtenir une clé API
|
||||
3. Tableau de bord → Ajouter clé API
|
||||
|
||||
**Utilisez :** `kimi/kimi-latest`
|
||||
|
||||
**Conseil Pro :** 9 $/mois fixe pour 10M tokens = 0,90 $/1M de coût effectif !
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>🆓 Fournisseurs GRATUITS (Backup d'urgence)</b></summary>
|
||||
|
||||
### iFlow (8 modèles GRATUITS)
|
||||
|
||||
```bash
|
||||
Tableau de bord → Connecter iFlow
|
||||
→ Connexion OAuth iFlow
|
||||
→ Utilisation illimitée
|
||||
|
||||
Modèles :
|
||||
if/kimi-k2-thinking
|
||||
if/qwen3-coder-plus
|
||||
if/glm-4.7
|
||||
if/minimax-m2
|
||||
if/deepseek-r1
|
||||
```
|
||||
|
||||
### Qwen (3 modèles GRATUITS)
|
||||
|
||||
```bash
|
||||
Tableau de bord → Connecter Qwen
|
||||
→ Autorisation par code d'appareil
|
||||
→ Utilisation illimitée
|
||||
|
||||
Modèles :
|
||||
qw/qwen3-coder-plus
|
||||
qw/qwen3-coder-flash
|
||||
```
|
||||
|
||||
### Kiro (Claude GRATUIT)
|
||||
|
||||
```bash
|
||||
Tableau de bord → Connecter Kiro
|
||||
→ AWS Builder ID ou Google/GitHub
|
||||
→ Utilisation illimitée
|
||||
|
||||
Modèles :
|
||||
kr/claude-sonnet-4.5
|
||||
kr/claude-haiku-4.5
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>🎨 Créer des combos</b></summary>
|
||||
|
||||
### Exemple 1 : Maximiser l'abonnement → Backup économique
|
||||
|
||||
```
|
||||
Tableau de bord → Combos → Créer nouveau
|
||||
|
||||
Nom : premium-coding
|
||||
Modèles :
|
||||
1. cc/claude-opus-4-6 (Abonnement principal)
|
||||
2. glm/glm-4.7 (Backup économique, $0.6/1M)
|
||||
3. minimax/MiniMax-M2.1 (Fallback le moins cher, $0.20/1M)
|
||||
|
||||
Utilisez en CLI : premium-coding
|
||||
```
|
||||
|
||||
### Exemple 2 : Gratuit uniquement (Zéro coût)
|
||||
|
||||
```
|
||||
Nom : free-combo
|
||||
Modèles :
|
||||
1. gc/gemini-3-flash-preview (180K gratuits/mois)
|
||||
2. if/kimi-k2-thinking (illimité)
|
||||
3. qw/qwen3-coder-plus (illimité)
|
||||
|
||||
Coût : 0 $ pour toujours !
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>🔧 Intégration CLI</b></summary>
|
||||
|
||||
### Cursor IDE
|
||||
|
||||
```
|
||||
Paramètres → Modèles → Avancé :
|
||||
OpenAI API Base URL : http://localhost:20128/v1
|
||||
OpenAI API Key : [du tableau de bord OmniRoute]
|
||||
Model : cc/claude-opus-4-6
|
||||
```
|
||||
|
||||
### Claude Code
|
||||
|
||||
Utilisez la page **CLI Tools** dans le tableau de bord pour la configuration en un clic, ou modifiez `~/.claude/settings.json` manuellement.
|
||||
|
||||
### Codex CLI
|
||||
|
||||
```bash
|
||||
export OPENAI_BASE_URL="http://localhost:20128"
|
||||
export OPENAI_API_KEY="your-omniroute-api-key"
|
||||
|
||||
codex "your prompt"
|
||||
```
|
||||
|
||||
### OpenClaw
|
||||
|
||||
**Option 1 — Tableau de bord (recommandé) :**
|
||||
|
||||
```
|
||||
Tableau de bord → CLI Tools → OpenClaw → Sélectionner modèle → Appliquer
|
||||
```
|
||||
|
||||
**Option 2 — Manuel :** Modifier `~/.openclaw/openclaw.json` :
|
||||
|
||||
```json
|
||||
{
|
||||
"models": {
|
||||
"providers": {
|
||||
"omniroute": {
|
||||
"baseUrl": "http://127.0.0.1:20128/v1",
|
||||
"apiKey": "sk_omniroute",
|
||||
"api": "openai-completions"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> **Note :** OpenClaw fonctionne uniquement avec OmniRoute local. Utilisez `127.0.0.1` au lieu de `localhost` pour éviter les problèmes de résolution IPv6.
|
||||
|
||||
### Cline / Continue / RooCode
|
||||
|
||||
```
|
||||
Paramètres → Configuration API :
|
||||
Fournisseur : OpenAI Compatible
|
||||
Base URL : http://localhost:20128/v1
|
||||
API Key : [du tableau de bord OmniRoute]
|
||||
Model : if/kimi-k2-thinking
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## 📊 Modèles disponibles
|
||||
|
||||
<details>
|
||||
<summary><b>Voir tous les modèles disponibles</b></summary>
|
||||
|
||||
**Claude Code (`cc/`)** - Pro/Max :
|
||||
|
||||
- `cc/claude-opus-4-6`
|
||||
- `cc/claude-sonnet-4-5-20250929`
|
||||
- `cc/claude-haiku-4-5-20251001`
|
||||
|
||||
**Codex (`cx/`)** - Plus/Pro :
|
||||
|
||||
- `cx/gpt-5.2-codex`
|
||||
- `cx/gpt-5.1-codex-max`
|
||||
|
||||
**Gemini CLI (`gc/`)** - GRATUIT :
|
||||
|
||||
- `gc/gemini-3-flash-preview`
|
||||
- `gc/gemini-2.5-pro`
|
||||
|
||||
**GitHub Copilot (`gh/`)** :
|
||||
|
||||
- `gh/gpt-5`
|
||||
- `gh/claude-4.5-sonnet`
|
||||
|
||||
**NVIDIA NIM (`nvidia/`)** - Crédits GRATUITS :
|
||||
|
||||
- `nvidia/llama-3.3-70b-instruct`
|
||||
- `nvidia/mistral-7b-instruct`
|
||||
- 50+ modèles sur [build.nvidia.com](https://build.nvidia.com)
|
||||
|
||||
**GLM (`glm/`)** - $0.6/1M :
|
||||
|
||||
- `glm/glm-4.7`
|
||||
|
||||
**MiniMax (`minimax/`)** - $0.2/1M :
|
||||
|
||||
- `minimax/MiniMax-M2.1`
|
||||
|
||||
**iFlow (`if/`)** - GRATUIT :
|
||||
|
||||
- `if/kimi-k2-thinking`
|
||||
- `if/qwen3-coder-plus`
|
||||
- `if/deepseek-r1`
|
||||
- `if/glm-4.7`
|
||||
- `if/minimax-m2`
|
||||
|
||||
**Qwen (`qw/`)** - GRATUIT :
|
||||
|
||||
- `qw/qwen3-coder-plus`
|
||||
- `qw/qwen3-coder-flash`
|
||||
|
||||
**Kiro (`kr/`)** - GRATUIT :
|
||||
|
||||
- `kr/claude-sonnet-4.5`
|
||||
- `kr/claude-haiku-4.5`
|
||||
|
||||
**OpenRouter (`or/`)** - 100+ modèles :
|
||||
|
||||
- `or/anthropic/claude-4-sonnet`
|
||||
- `or/google/gemini-2.5-pro`
|
||||
- Tout modèle de [openrouter.ai/models](https://openrouter.ai/models)
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Évaluations (Evals)
|
||||
|
||||
OmniRoute inclut un framework d'évaluation intégré pour tester la qualité des réponses LLM contre un golden set. Accès via **Analytics → Evals** dans le tableau de bord.
|
||||
|
||||
### Golden Set intégré
|
||||
|
||||
Le « OmniRoute Golden Set » préchargé contient 10 cas de test :
|
||||
|
||||
- Salutations, mathématiques, géographie, génération de code
|
||||
- Conformité format JSON, traduction, markdown
|
||||
- Rejet de sécurité (contenu nocif), comptage, logique booléenne
|
||||
|
||||
### Stratégies d'évaluation
|
||||
|
||||
| Stratégie | Description | Exemple |
|
||||
| ---------- | -------------------------------------------------------------- | -------------------------------- |
|
||||
| `exact` | La sortie doit correspondre exactement | `"4"` |
|
||||
| `contains` | La sortie doit contenir la sous-chaîne (insensible à la casse) | `"Paris"` |
|
||||
| `regex` | La sortie doit correspondre au motif regex | `"1.*2.*3"` |
|
||||
| `custom` | Fonction JS personnalisée retourne true/false | `(output) => output.length > 10` |
|
||||
|
||||
---
|
||||
|
||||
## 🐛 Dépannage
|
||||
|
||||
<details>
|
||||
<summary><b>Cliquez pour développer le guide de dépannage</b></summary>
|
||||
|
||||
**« Language model did not provide messages »**
|
||||
|
||||
- Quota du fournisseur épuisé → Vérifiez le suivi de quota dans le tableau de bord
|
||||
- Solution : Utilisez un combo avec fallback ou passez à un niveau moins cher
|
||||
|
||||
**Rate limiting**
|
||||
|
||||
- Quota d'abonnement épuisé → Fallback vers GLM/MiniMax
|
||||
- Ajoutez un combo : `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
|
||||
|
||||
**Token OAuth expiré**
|
||||
|
||||
- Renouvelé automatiquement par OmniRoute
|
||||
- Si le problème persiste : Tableau de bord → Fournisseur → Reconnecter
|
||||
|
||||
**Coûts élevés**
|
||||
|
||||
- Vérifiez les statistiques d'utilisation dans Tableau de bord → Coûts
|
||||
- Changez le modèle principal pour GLM/MiniMax
|
||||
- Utilisez le niveau gratuit (Gemini CLI, iFlow) pour les tâches non critiques
|
||||
|
||||
**Le tableau de bord s'ouvre sur le mauvais port**
|
||||
|
||||
- Définissez `PORT=20128` et `NEXT_PUBLIC_BASE_URL=http://localhost:20128`
|
||||
|
||||
**Erreurs de cloud sync**
|
||||
|
||||
- Vérifiez que `BASE_URL` pointe vers votre instance en cours d'exécution
|
||||
- Vérifiez que `CLOUD_URL` pointe vers le point de terminaison cloud attendu
|
||||
- Gardez les valeurs `NEXT_PUBLIC_*` alignées avec les valeurs du serveur
|
||||
|
||||
**Le premier login ne fonctionne pas**
|
||||
|
||||
- Vérifiez `INITIAL_PASSWORD` dans `.env`
|
||||
- Si non défini, le mot de passe par défaut est `123456`
|
||||
|
||||
**Pas de logs de requêtes**
|
||||
|
||||
- Définissez `ENABLE_REQUEST_LOGS=true` dans `.env`
|
||||
|
||||
**Le test de connexion affiche « Invalid » pour les fournisseurs compatibles OpenAI**
|
||||
|
||||
- Beaucoup de fournisseurs n'exposent pas le point de terminaison `/models`
|
||||
- OmniRoute v0.9.0+ inclut une validation de secours via chat completions
|
||||
- Assurez-vous que l'URL de base inclut le suffixe `/v1`
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Stack technologique
|
||||
|
||||
- **Runtime** : Node.js 20+
|
||||
- **Langage** : TypeScript 5.9 — **100% TypeScript** dans `src/` et `open-sse/` (v0.9.0)
|
||||
- **Framework** : Next.js 16 + React 19 + Tailwind CSS 4
|
||||
- **Base de données** : LowDB (JSON) + SQLite (état du domaine + logs proxy)
|
||||
- **Streaming** : Server-Sent Events (SSE)
|
||||
- **Auth** : OAuth 2.0 (PKCE) + JWT + API Keys
|
||||
- **Tests** : Node.js test runner (368+ tests unitaires)
|
||||
- **CI/CD** : GitHub Actions (publication automatique npm + Docker Hub lors du release)
|
||||
- **Site web** : [omniroute.online](https://omniroute.online)
|
||||
- **Package** : [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)
|
||||
- **Docker** : [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)
|
||||
- **Résilience** : Circuit breaker, backoff exponentiel, anti-thundering herd, spoofing TLS
|
||||
|
||||
---
|
||||
|
||||
## 📖 Documentation
|
||||
|
||||
| Document | Description |
|
||||
| ------------------------------------------ | --------------------------------------------------- |
|
||||
| [Guide utilisateur](docs/USER_GUIDE.md) | Fournisseurs, combos, intégration CLI, déploiement |
|
||||
| [Référence API](docs/API_REFERENCE.md) | Tous les endpoints avec exemples |
|
||||
| [Dépannage](docs/TROUBLESHOOTING.md) | Problèmes courants et solutions |
|
||||
| [Architecture](docs/ARCHITECTURE.md) | Architecture système et détails internes |
|
||||
| [Contribuer](CONTRIBUTING.md) | Configuration de développement et directives |
|
||||
| [Spécification OpenAPI](docs/openapi.yaml) | Spécification OpenAPI 3.0 |
|
||||
| [Politique de sécurité](SECURITY.md) | Signalement de vulnérabilités et pratiques sécurité |
|
||||
|
||||
---
|
||||
|
||||
## 📧 Support
|
||||
|
||||
- **Site web** : [omniroute.online](https://omniroute.online)
|
||||
- **GitHub** : [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
|
||||
- **Issues** : [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
|
||||
- **Projet original** : [9router par decolua](https://github.com/decolua/9router)
|
||||
|
||||
---
|
||||
|
||||
## 👥 Contributeurs
|
||||
|
||||
[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
|
||||
|
||||
### Comment contribuer
|
||||
|
||||
1. Forkez le dépôt
|
||||
2. Créez votre branche de fonctionnalité (`git checkout -b feature/amazing-feature`)
|
||||
3. Committez vos changements (`git commit -m 'Add amazing feature'`)
|
||||
4. Poussez vers la branche (`git push origin feature/amazing-feature`)
|
||||
5. Ouvrez une Pull Request
|
||||
|
||||
Consultez [CONTRIBUTING.md](CONTRIBUTING.md) pour les directives détaillées.
|
||||
|
||||
### Publier une nouvelle version
|
||||
|
||||
```bash
|
||||
# Créer un release — la publication npm est automatique
|
||||
gh release create v0.9.0 --title "v0.9.0" --generate-notes
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Historique des Stars
|
||||
|
||||
<a href="https://star-history.com/#diegosouzapw/OmniRoute&Date">
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=diegosouzapw/OmniRoute&type=Date&theme=dark" />
|
||||
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=diegosouzapw/OmniRoute&type=Date" />
|
||||
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=diegosouzapw/OmniRoute&type=Date" />
|
||||
</picture>
|
||||
</a>
|
||||
|
||||
---
|
||||
|
||||
## 🙏 Remerciements
|
||||
|
||||
Remerciements spéciaux à **[9router](https://github.com/decolua/9router)** par **[decolua](https://github.com/decolua)** — le projet original qui a inspiré ce fork. OmniRoute construit sur cette base incroyable avec des fonctionnalités supplémentaires, des APIs multi-modales et une réécriture complète en TypeScript.
|
||||
|
||||
Remerciements spéciaux à **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — l'implémentation originale en Go qui a inspiré ce portage en JavaScript.
|
||||
|
||||
---
|
||||
|
||||
## 📄 Licence
|
||||
|
||||
Licence MIT — voir [LICENSE](LICENSE) pour les détails.
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
<sub>Fait avec ❤️ pour les développeurs qui codent 24/7</sub>
|
||||
<br/>
|
||||
<sub><a href="https://omniroute.online">omniroute.online</a></sub>
|
||||
</div>
|
||||
995
README.it.md
Normal file
995
README.it.md
Normal file
@@ -0,0 +1,995 @@
|
||||
<div align="center">
|
||||
<img src="./images/omniroute.png" alt="OmniRoute Dashboard" width="800"/>
|
||||
|
||||
# 🚀 OmniRoute — Il Gateway IA Gratuito
|
||||
|
||||
### Non smettere mai di programmare. Routing intelligente verso **modelli IA GRATUITI e economici** con fallback automatico.
|
||||
|
||||
_Il tuo proxy API universale — un endpoint, 36+ provider, zero downtime._
|
||||
|
||||
**Chat Completions • Embeddings • Generazione Immagini • Audio • Reranking • 100% TypeScript**
|
||||
|
||||
---
|
||||
|
||||
### 🤖 Provider IA gratuito per i tuoi agenti di programmazione preferiti
|
||||
|
||||
_Connetti qualsiasi IDE o strumento CLI con IA tramite OmniRoute — gateway API gratuito per programmazione illimitata._
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/cline/cline">
|
||||
<img src="./public/providers/openclaw.png" alt="OpenClaw" width="48"/><br/>
|
||||
<b>OpenClaw</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 205K</sub>
|
||||
</td>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/HKUDS/nanobot">
|
||||
<img src="./public/providers/nanobot.png" alt="NanoBot" width="48"/><br/>
|
||||
<b>NanoBot</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 20.9K</sub>
|
||||
</td>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/sipeed/picoclaw">
|
||||
<img src="./public/providers/picoclaw.jpg" alt="PicoClaw" width="48"/><br/>
|
||||
<b>PicoClaw</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 14.6K</sub>
|
||||
</td>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/zeroclaw-labs/zeroclaw">
|
||||
<img src="./public/providers/zeroclaw.png" alt="ZeroClaw" width="48"/><br/>
|
||||
<b>ZeroClaw</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 9.9K</sub>
|
||||
</td>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/nearai/ironclaw">
|
||||
<img src="./public/providers/ironclaw.png" alt="IronClaw" width="48"/><br/>
|
||||
<b>IronClaw</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 2.1K</sub>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/anomalyco/opencode">
|
||||
<img src="./public/providers/opencode.svg" alt="OpenCode" width="48"/><br/>
|
||||
<b>OpenCode</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 106K</sub>
|
||||
</td>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/openai/codex">
|
||||
<img src="./public/providers/codex.png" alt="Codex CLI" width="48"/><br/>
|
||||
<b>Codex CLI</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 60.8K</sub>
|
||||
</td>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/anthropics/claude-code">
|
||||
<img src="./public/providers/claude.png" alt="Claude Code" width="48"/><br/>
|
||||
<b>Claude Code</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 67.3K</sub>
|
||||
</td>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/google-gemini/gemini-cli">
|
||||
<img src="./public/providers/gemini-cli.png" alt="Gemini CLI" width="48"/><br/>
|
||||
<b>Gemini CLI</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 94.7K</sub>
|
||||
</td>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/Kilo-Org/kilocode">
|
||||
<img src="./public/providers/kilocode.png" alt="Kilo Code" width="48"/><br/>
|
||||
<b>Kilo Code</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 15.5K</sub>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<sub>📡 Tutti gli agenti si connettono via <code>http://localhost:20128/v1</code> o <code>http://cloud.omniroute.online/v1</code> — una configurazione, modelli e quota illimitati</sub>
|
||||
|
||||
---
|
||||
|
||||
[](https://www.npmjs.com/package/omniroute)
|
||||
[](https://hub.docker.com/r/diegosouzapw/omniroute)
|
||||
[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
|
||||
[](https://omniroute.online)
|
||||
|
||||
[🌐 Sito Web](https://omniroute.online) • [🚀 Avvio Rapido](#-avvio-rapido) • [💡 Funzionalità](#-funzionalità-principali) • [📖 Docs](#-documentazione) • [💰 Prezzi](#-panoramica-prezzi)
|
||||
|
||||
🌐 **Disponibile in:** [English](README.md) | [Português](README.pt-BR.md) | [Español](README.es.md) | [Русский](README.ru.md) | [中文](README.zh-CN.md) | [Deutsch](README.de.md) | [Français](README.fr.md) | [Italiano](README.it.md)
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## 🤔 Perché OmniRoute?
|
||||
|
||||
**Smetti di sprecare soldi e di sbattere contro i limiti:**
|
||||
|
||||
- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> La quota dell'abbonamento scade inutilizzata ogni mese
|
||||
- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> I limiti di rate ti fermano nel mezzo della programmazione
|
||||
- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> API costose ($20-50/mese per provider)
|
||||
- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> Cambio manuale tra provider
|
||||
|
||||
**OmniRoute risolve tutto questo:**
|
||||
|
||||
- ✅ **Massimizza gli abbonamenti** — Traccia le quote, usa tutto prima del reset
|
||||
- ✅ **Fallback automatico** — Abbonamento → API Key → Economico → Gratuito, zero downtime
|
||||
- ✅ **Multi-account** — Round-robin tra account per provider
|
||||
- ✅ **Universale** — Funziona con Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, qualsiasi strumento CLI
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Come Funziona
|
||||
|
||||
```
|
||||
┌─────────────┐
|
||||
│ Il tuo CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)
|
||||
│ Tool │
|
||||
└──────┬──────┘
|
||||
│ http://localhost:20128/v1
|
||||
↓
|
||||
┌─────────────────────────────────────────┐
|
||||
│ OmniRoute (Router Intelligente) │
|
||||
│ • Traduzione formato (OpenAI ↔ Claude) │
|
||||
│ • Tracciamento quote + Embeddings + Immagini │
|
||||
│ • Rinnovo automatico dei token │
|
||||
└──────┬──────────────────────────────────┘
|
||||
│
|
||||
├─→ [Tier 1: ABBONAMENTO] Claude Code, Codex, Gemini CLI
|
||||
│ ↓ quota esaurita
|
||||
├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, ecc.
|
||||
│ ↓ limite budget
|
||||
├─→ [Tier 3: ECONOMICO] GLM ($0.6/1M), MiniMax ($0.2/1M)
|
||||
│ ↓ limite budget
|
||||
└─→ [Tier 4: GRATUITO] iFlow, Qwen, Kiro (illimitato)
|
||||
|
||||
Risultato: Non smettere mai di programmare, costo minimo
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚡ Avvio Rapido
|
||||
|
||||
**1. Installa globalmente:**
|
||||
|
||||
```bash
|
||||
npm install -g omniroute
|
||||
omniroute
|
||||
```
|
||||
|
||||
🎉 La Dashboard si apre su `http://localhost:20128`
|
||||
|
||||
| Comando | Descrizione |
|
||||
| ----------------------- | ------------------------------------------- |
|
||||
| `omniroute` | Avviare il server (porta predefinita 20128) |
|
||||
| `omniroute --port 3000` | Usare una porta personalizzata |
|
||||
| `omniroute --no-open` | Non aprire il browser automaticamente |
|
||||
| `omniroute --help` | Mostrare l'aiuto |
|
||||
|
||||
**2. Connetti un provider GRATUITO:**
|
||||
|
||||
Dashboard → Provider → Connetti **Claude Code** o **Antigravity** → Login OAuth → Fatto!
|
||||
|
||||
**3. Usa nel tuo strumento CLI:**
|
||||
|
||||
```
|
||||
Claude Code/Codex/Gemini CLI/OpenClaw/Cursor/Cline Impostazioni:
|
||||
Endpoint: http://localhost:20128/v1
|
||||
API Key: [copia dalla dashboard]
|
||||
Model: if/kimi-k2-thinking
|
||||
```
|
||||
|
||||
**Tutto qui!** Inizia a programmare con modelli IA GRATUITI.
|
||||
|
||||
**Alternativa — eseguire dal codice sorgente:**
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
npm install
|
||||
PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🐳 Docker
|
||||
|
||||
OmniRoute è disponibile come immagine Docker pubblica su [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
|
||||
|
||||
**Avvio rapido:**
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
--name omniroute \
|
||||
--restart unless-stopped \
|
||||
-p 20128:20128 \
|
||||
-v omniroute-data:/app/data \
|
||||
diegosouzapw/omniroute:latest
|
||||
```
|
||||
|
||||
**Con file di ambiente:**
|
||||
|
||||
```bash
|
||||
# Copia e modifica il .env prima
|
||||
cp .env.example .env
|
||||
|
||||
docker run -d \
|
||||
--name omniroute \
|
||||
--restart unless-stopped \
|
||||
--env-file .env \
|
||||
-p 20128:20128 \
|
||||
-v omniroute-data:/app/data \
|
||||
diegosouzapw/omniroute:latest
|
||||
```
|
||||
|
||||
**Con Docker Compose:**
|
||||
|
||||
```bash
|
||||
# Profilo base (senza strumenti CLI)
|
||||
docker compose --profile base up -d
|
||||
|
||||
# Profilo CLI (Claude Code, Codex, OpenClaw integrati)
|
||||
docker compose --profile cli up -d
|
||||
```
|
||||
|
||||
| Immagine | Tag | Dimensione | Descrizione |
|
||||
| ------------------------ | -------- | ---------- | ----------------------- |
|
||||
| `diegosouzapw/omniroute` | `latest` | ~250MB | Ultima versione stabile |
|
||||
| `diegosouzapw/omniroute` | `0.9.0` | ~250MB | Versione attuale |
|
||||
|
||||
---
|
||||
|
||||
## 💰 Panoramica Prezzi
|
||||
|
||||
| Tier | Provider | Costo | Reset Quota | Ideale Per |
|
||||
| ------------------ | ----------------- | ---------------------------- | --------------------- | ------------------------------- |
|
||||
| **💳 ABBONAMENTO** | Claude Code (Pro) | $20/mese | 5h + settimanale | Già abbonato |
|
||||
| | Codex (Plus/Pro) | $20-200/mese | 5h + settimanale | Utenti OpenAI |
|
||||
| | Gemini CLI | **GRATUITO** | 180K/mese + 1K/giorno | Tutti! |
|
||||
| | GitHub Copilot | $10-19/mese | Mensile | Utenti GitHub |
|
||||
| **🔑 API KEY** | NVIDIA NIM | **GRATUITO** (1000 crediti) | Una tantum | Test gratuiti |
|
||||
| | DeepSeek | A consumo | Nessuno | Miglior rapporto qualità-prezzo |
|
||||
| | Groq | Livello gratis + a pagamento | Limitato | Inferenza ultra-veloce |
|
||||
| | xAI (Grok) | A consumo | Nessuno | Modelli Grok |
|
||||
| | Mistral | Livello gratis + a pagamento | Limitato | IA Europea |
|
||||
| | OpenRouter | A consumo | Nessuno | 100+ modelli |
|
||||
| **💰 ECONOMICO** | GLM-4.7 | $0.6/1M | Giornaliero 10h | Backup economico |
|
||||
| | MiniMax M2.1 | $0.2/1M | Rotativo 5h | Opzione più economica |
|
||||
| | Kimi K2 | $9/mese fisso | 10M token/mese | Costo prevedibile |
|
||||
| **🆓 GRATUITO** | iFlow | $0 | Illimitato | 8 modelli gratuiti |
|
||||
| | Qwen | $0 | Illimitato | 3 modelli gratuiti |
|
||||
| | Kiro | $0 | Illimitato | Claude gratuito |
|
||||
|
||||
**💡 Consiglio Pro:** Inizia con Gemini CLI (180K gratis/mese) + iFlow (illimitato gratis) = $0 di costo!
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Casi d'Uso
|
||||
|
||||
### Caso 1: "Ho un abbonamento Claude Pro"
|
||||
|
||||
**Problema:** La quota scade inutilizzata, limiti di rate durante la programmazione intensa
|
||||
|
||||
```
|
||||
Combo: "maximize-claude"
|
||||
1. cc/claude-opus-4-6 (usa l'abbonamento al massimo)
|
||||
2. glm/glm-4.7 (backup economico quando la quota è esaurita)
|
||||
3. if/kimi-k2-thinking (fallback d'emergenza gratuito)
|
||||
|
||||
Costo mensile: $20 (abbonamento) + ~$5 (backup) = $25 totale
|
||||
vs. $20 + sbattere contro i limiti = frustrazione
|
||||
```
|
||||
|
||||
### Caso 2: "Voglio costo zero"
|
||||
|
||||
**Problema:** Non può permettersi abbonamenti, ha bisogno di IA affidabile per programmare
|
||||
|
||||
```
|
||||
Combo: "free-forever"
|
||||
1. gc/gemini-3-flash (180K gratis/mese)
|
||||
2. if/kimi-k2-thinking (illimitato gratis)
|
||||
3. qw/qwen3-coder-plus (illimitato gratis)
|
||||
|
||||
Costo mensile: $0
|
||||
Qualità: Modelli pronti per la produzione
|
||||
```
|
||||
|
||||
### Caso 3: "Devo programmare 24/7, senza interruzioni"
|
||||
|
||||
**Problema:** Scadenze strette, non può permettersi downtime
|
||||
|
||||
```
|
||||
Combo: "always-on"
|
||||
1. cc/claude-opus-4-6 (migliore qualità)
|
||||
2. cx/gpt-5.2-codex (secondo abbonamento)
|
||||
3. glm/glm-4.7 (economico, reset giornaliero)
|
||||
4. minimax/MiniMax-M2.1 (più economico, reset 5h)
|
||||
5. if/kimi-k2-thinking (gratuito illimitato)
|
||||
|
||||
Risultato: 5 livelli di fallback = zero downtime
|
||||
```
|
||||
|
||||
### Caso 4: "Voglio IA GRATUITA in OpenClaw"
|
||||
|
||||
**Problema:** Ha bisogno di assistente IA nelle app di messaggistica, completamente gratuito
|
||||
|
||||
```
|
||||
Combo: "openclaw-free"
|
||||
1. if/glm-4.7 (illimitato gratis)
|
||||
2. if/minimax-m2.1 (illimitato gratis)
|
||||
3. if/kimi-k2-thinking (illimitato gratis)
|
||||
|
||||
Costo mensile: $0
|
||||
Accesso via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 💡 Funzionalità Principali
|
||||
|
||||
### 🧠 Routing & Intelligenza
|
||||
|
||||
| Funzionalità | Cosa Fa |
|
||||
| ---------------------------------------- | ----------------------------------------------------------------------------- |
|
||||
| 🎯 **Fallback intelligente 4 livelli** | Auto-routing: Abbonamento → API Key → Economico → Gratuito |
|
||||
| 📊 **Tracciamento quote in tempo reale** | Conteggio token live + countdown reset per provider |
|
||||
| 🔄 **Traduzione di formato** | OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro trasparente |
|
||||
| 👥 **Supporto multi-account** | Account multipli per provider con selezione intelligente |
|
||||
| 🔄 **Rinnovo automatico dei token** | I token OAuth si rinnovano automaticamente con retry |
|
||||
| 🎨 **Combo personalizzati** | 6 strategie: fill-first, round-robin, p2c, random, least-used, cost-optimized |
|
||||
| 🧩 **Modelli personalizzati** | Aggiungi qualsiasi ID modello a qualsiasi provider |
|
||||
| 🌐 **Router wildcard** | Instrada pattern `provider/*` verso qualsiasi provider dinamicamente |
|
||||
| 🧠 **Budget di ragionamento** | Modalità passthrough, auto, custom e adaptive per modelli di ragionamento |
|
||||
| 💬 **Iniezione System Prompt** | System prompt globale applicato a tutte le richieste |
|
||||
| 📄 **API Responses** | Supporto completo per OpenAI Responses API (`/v1/responses`) per Codex |
|
||||
|
||||
### 🎵 API Multi-modali
|
||||
|
||||
| Funzionalità | Cosa Fa |
|
||||
| --------------------------- | ---------------------------------------------------- |
|
||||
| 🖼️ **Generazione immagini** | `/v1/images/generations` — 4 provider, 9+ modelli |
|
||||
| 📐 **Embeddings** | `/v1/embeddings` — 6 provider, 9+ modelli |
|
||||
| 🎤 **Trascrizione audio** | `/v1/audio/transcriptions` — Compatibile Whisper |
|
||||
| 🔊 **Testo a voce** | `/v1/audio/speech` — Sintesi audio multi-provider |
|
||||
| 🛡️ **Moderazioni** | `/v1/moderations` — Controlli di sicurezza |
|
||||
| 🔀 **Reranking** | `/v1/rerank` — Riclassificazione rilevanza documenti |
|
||||
|
||||
### 🛡️ Resilienza & Sicurezza
|
||||
|
||||
| Funzionalità | Cosa Fa |
|
||||
| ------------------------------- | -------------------------------------------------------------- |
|
||||
| 🔌 **Circuit Breaker** | Apertura/chiusura auto per provider con soglie configurabili |
|
||||
| 🛡️ **Anti-Thundering Herd** | Mutex + semaforo rate-limit per provider con API key |
|
||||
| 🧠 **Cache semantica** | Cache a due livelli (firma + semantica) riduce costi e latenza |
|
||||
| ⚡ **Idempotenza richieste** | Finestra dedup 5s per richieste duplicate |
|
||||
| 🔒 **Spoofing TLS Fingerprint** | Bypass rilevamento bot tramite wreq-js |
|
||||
| 🌐 **Filtro IP** | Allowlist/blocklist per controllo accesso API |
|
||||
| 📊 **Rate limit modificabili** | RPM, gap minimo e concorrenza massima configurabili |
|
||||
|
||||
### 📊 Osservabilità & Analytics
|
||||
|
||||
| Funzionalità | Cosa Fa |
|
||||
| ----------------------------- | ------------------------------------------------------------ |
|
||||
| 📝 **Log richieste** | Modalità debug con log completi richiesta/risposta |
|
||||
| 💾 **Log SQLite** | Log proxy persistenti che sopravvivono ai riavvii |
|
||||
| 📊 **Dashboard analytics** | Recharts: card statistiche, grafico uso, tabella provider |
|
||||
| 📈 **Tracciamento progresso** | Eventi SSE di progresso opt-in per lo streaming |
|
||||
| 🧪 **Valutazioni LLM** | Test con golden set e 4 strategie di corrispondenza |
|
||||
| 🔍 **Telemetria richieste** | Aggregazione latenza p50/p95/p99 + tracciamento X-Request-Id |
|
||||
| 📋 **Log + Quote** | Pagine dedicate per navigazione log e tracciamento quote |
|
||||
| 🏥 **Dashboard salute** | Uptime, stati circuit breaker, lockout, statistiche cache |
|
||||
| 💰 **Tracciamento costi** | Gestione budget + configurazione prezzi per modello |
|
||||
|
||||
### ☁️ Deploy & Sincronizzazione
|
||||
|
||||
| Funzionalità | Cosa Fa |
|
||||
| -------------------------------- | -------------------------------------------------------------------------------- |
|
||||
| 💾 **Cloud Sync** | Sincronizza impostazioni tra dispositivi via Cloudflare Workers |
|
||||
| 🌐 **Deploy ovunque** | Localhost, VPS, Docker, Cloudflare Workers |
|
||||
| 🔑 **Gestione API Key** | Genera, ruota e limita API key per provider |
|
||||
| 🧙 **Assistente configurazione** | Setup guidato in 4 passaggi per nuovi utenti |
|
||||
| 🔧 **Dashboard CLI Tools** | Configurazione con un clic per Claude, Codex, Cline, OpenClaw, Kilo, Antigravity |
|
||||
| 🔄 **Backup DB** | Backup e ripristino automatici di tutte le impostazioni |
|
||||
|
||||
<details>
|
||||
<summary><b>📖 Dettagli funzionalità</b></summary>
|
||||
|
||||
### 🎯 Fallback intelligente 4 livelli
|
||||
|
||||
Crea combo con fallback automatico:
|
||||
|
||||
```
|
||||
Combo: "my-coding-stack"
|
||||
1. cc/claude-opus-4-6 (il tuo abbonamento)
|
||||
2. nvidia/llama-3.3-70b (API NVIDIA gratuita)
|
||||
3. glm/glm-4.7 (backup economico, $0.6/1M)
|
||||
4. if/kimi-k2-thinking (fallback gratuito)
|
||||
|
||||
→ Cambia automaticamente quando la quota si esaurisce o si verificano errori
|
||||
```
|
||||
|
||||
### 📊 Tracciamento quote in tempo reale
|
||||
|
||||
- Consumo token per provider
|
||||
- Countdown reset (5 ore, giornaliero, settimanale)
|
||||
- Stima dei costi per livelli a pagamento
|
||||
- Report spese mensili
|
||||
|
||||
### 🔄 Traduzione di formato
|
||||
|
||||
Traduzione trasparente tra formati:
|
||||
|
||||
- **OpenAI** ↔ **Claude** ↔ **Gemini** ↔ **OpenAI Responses**
|
||||
- Il tuo CLI invia in formato OpenAI → OmniRoute traduce → Il provider riceve il formato nativo
|
||||
- Funziona con qualsiasi strumento che supporti endpoint OpenAI personalizzati
|
||||
|
||||
### 👥 Supporto multi-account
|
||||
|
||||
- Aggiungi account multipli per provider
|
||||
- Round-robin automatico o routing per priorità
|
||||
- Fallback all'account successivo quando la quota viene raggiunta
|
||||
|
||||
### 🔄 Rinnovo automatico dei token
|
||||
|
||||
- I token OAuth si rinnovano automaticamente prima della scadenza
|
||||
- Nessuna necessità di ri-autenticazione manuale
|
||||
- Esperienza trasparente su tutti i provider
|
||||
|
||||
### 🎨 Combo personalizzati
|
||||
|
||||
- Crea combinazioni di modelli illimitate
|
||||
- 6 strategie: fill-first, round-robin, power-of-two-choices, random, least-used, cost-optimized
|
||||
- Condividi combo tra dispositivi con Cloud Sync
|
||||
|
||||
### 🏥 Dashboard salute
|
||||
|
||||
- Stato del sistema (uptime, versione, utilizzo memoria)
|
||||
- Stati circuit breaker per provider (Closed/Open/Half-Open)
|
||||
- Stato rate limit e lockout attivi
|
||||
- Statistiche cache firme
|
||||
- Telemetria latenza (p50/p95/p99) + cache prompt
|
||||
- Reset salute con un clic
|
||||
|
||||
### 🔧 Playground del traduttore
|
||||
|
||||
- Debug, test e visualizzazione delle traduzioni di formato API
|
||||
- Invia richieste e vedi come OmniRoute traduce tra formati dei provider
|
||||
- Inestimabile per risolvere problemi di integrazione
|
||||
|
||||
### 💾 Cloud Sync
|
||||
|
||||
- Sincronizza provider, combo e impostazioni tra dispositivi
|
||||
- Sincronizzazione in background automatica
|
||||
- Archiviazione criptata sicura
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## 📖 Guida alla Configurazione
|
||||
|
||||
<details>
|
||||
<summary><b>💳 Provider per abbonamento</b></summary>
|
||||
|
||||
### Claude Code (Pro/Max)
|
||||
|
||||
```bash
|
||||
Dashboard → Provider → Connetti Claude Code
|
||||
→ Login OAuth → Rinnovo automatico token
|
||||
→ Tracciamento quota 5h + settimanale
|
||||
|
||||
Modelli:
|
||||
cc/claude-opus-4-6
|
||||
cc/claude-sonnet-4-5-20250929
|
||||
cc/claude-haiku-4-5-20251001
|
||||
```
|
||||
|
||||
**Consiglio Pro:** Usa Opus per compiti complessi, Sonnet per velocità. OmniRoute traccia la quota per modello!
|
||||
|
||||
### OpenAI Codex (Plus/Pro)
|
||||
|
||||
```bash
|
||||
Dashboard → Provider → Connetti Codex
|
||||
→ Login OAuth (porta 1455)
|
||||
→ Reset 5h + settimanale
|
||||
|
||||
Modelli:
|
||||
cx/gpt-5.2-codex
|
||||
cx/gpt-5.1-codex-max
|
||||
```
|
||||
|
||||
### Gemini CLI (GRATUITO 180K/mese!)
|
||||
|
||||
```bash
|
||||
Dashboard → Provider → Connetti Gemini CLI
|
||||
→ Google OAuth
|
||||
→ 180K completions/mese + 1K/giorno
|
||||
|
||||
Modelli:
|
||||
gc/gemini-3-flash-preview
|
||||
gc/gemini-2.5-pro
|
||||
```
|
||||
|
||||
**Miglior valore:** Livello gratuito enorme! Usa prima dei livelli a pagamento.
|
||||
|
||||
### GitHub Copilot
|
||||
|
||||
```bash
|
||||
Dashboard → Provider → Connetti GitHub
|
||||
→ OAuth via GitHub
|
||||
→ Reset mensile (1° del mese)
|
||||
|
||||
Modelli:
|
||||
gh/gpt-5
|
||||
gh/claude-4.5-sonnet
|
||||
gh/gemini-3-pro
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>🔑 Provider per API Key</b></summary>
|
||||
|
||||
### NVIDIA NIM (GRATUITO 1000 crediti!)
|
||||
|
||||
1. Registrati: [build.nvidia.com](https://build.nvidia.com)
|
||||
2. Ottieni una API key gratuita (1000 crediti di inferenza inclusi)
|
||||
3. Dashboard → Aggiungi Provider → NVIDIA NIM:
|
||||
- API Key: `nvapi-your-key`
|
||||
|
||||
**Modelli:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct` e 50+ altri
|
||||
|
||||
**Consiglio Pro:** API compatibile OpenAI — funziona perfettamente con la traduzione di formato di OmniRoute!
|
||||
|
||||
### DeepSeek
|
||||
|
||||
1. Registrati: [platform.deepseek.com](https://platform.deepseek.com)
|
||||
2. Ottieni una API key
|
||||
3. Dashboard → Aggiungi Provider → DeepSeek
|
||||
|
||||
**Modelli:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`
|
||||
|
||||
### Groq (Livello gratuito disponibile!)
|
||||
|
||||
1. Registrati: [console.groq.com](https://console.groq.com)
|
||||
2. Ottieni una API key (livello gratuito incluso)
|
||||
3. Dashboard → Aggiungi Provider → Groq
|
||||
|
||||
**Modelli:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`
|
||||
|
||||
**Consiglio Pro:** Inferenza ultra-veloce — ideale per programmazione in tempo reale!
|
||||
|
||||
### OpenRouter (100+ modelli)
|
||||
|
||||
1. Registrati: [openrouter.ai](https://openrouter.ai)
|
||||
2. Ottieni una API key
|
||||
3. Dashboard → Aggiungi Provider → OpenRouter
|
||||
|
||||
**Modelli:** Accesso a 100+ modelli da tutti i principali provider tramite una singola API key.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>💰 Provider economici (Backup)</b></summary>
|
||||
|
||||
### GLM-4.7 (Reset giornaliero, $0.6/1M)
|
||||
|
||||
1. Registrati: [Zhipu AI](https://open.bigmodel.cn/)
|
||||
2. Ottieni la API key dal Coding Plan
|
||||
3. Dashboard → Aggiungi API Key:
|
||||
- Provider: `glm`
|
||||
- API Key: `your-key`
|
||||
|
||||
**Usa:** `glm/glm-4.7`
|
||||
|
||||
**Consiglio Pro:** Il Coding Plan offre 3× quota a 1/7 del costo! Reset giornaliero alle 10:00.
|
||||
|
||||
### MiniMax M2.1 (Reset 5h, $0.20/1M)
|
||||
|
||||
1. Registrati: [MiniMax](https://www.minimax.io/)
|
||||
2. Ottieni una API key
|
||||
3. Dashboard → Aggiungi API Key
|
||||
|
||||
**Usa:** `minimax/MiniMax-M2.1`
|
||||
|
||||
**Consiglio Pro:** L'opzione più economica per contesto lungo (1M token)!
|
||||
|
||||
### Kimi K2 ($9/mese fisso)
|
||||
|
||||
1. Abbonati: [Moonshot AI](https://platform.moonshot.ai/)
|
||||
2. Ottieni una API key
|
||||
3. Dashboard → Aggiungi API Key
|
||||
|
||||
**Usa:** `kimi/kimi-latest`
|
||||
|
||||
**Consiglio Pro:** $9/mese fisso per 10M token = $0.90/1M di costo effettivo!
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>🆓 Provider GRATUITI (Backup d'emergenza)</b></summary>
|
||||
|
||||
### iFlow (8 modelli GRATUITI)
|
||||
|
||||
```bash
|
||||
Dashboard → Connetti iFlow
|
||||
→ Login OAuth iFlow
|
||||
→ Utilizzo illimitato
|
||||
|
||||
Modelli:
|
||||
if/kimi-k2-thinking
|
||||
if/qwen3-coder-plus
|
||||
if/glm-4.7
|
||||
if/minimax-m2
|
||||
if/deepseek-r1
|
||||
```
|
||||
|
||||
### Qwen (3 modelli GRATUITI)
|
||||
|
||||
```bash
|
||||
Dashboard → Connetti Qwen
|
||||
→ Autorizzazione con codice dispositivo
|
||||
→ Utilizzo illimitato
|
||||
|
||||
Modelli:
|
||||
qw/qwen3-coder-plus
|
||||
qw/qwen3-coder-flash
|
||||
```
|
||||
|
||||
### Kiro (Claude GRATUITO)
|
||||
|
||||
```bash
|
||||
Dashboard → Connetti Kiro
|
||||
→ AWS Builder ID o Google/GitHub
|
||||
→ Utilizzo illimitato
|
||||
|
||||
Modelli:
|
||||
kr/claude-sonnet-4.5
|
||||
kr/claude-haiku-4.5
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>🎨 Creare combo</b></summary>
|
||||
|
||||
### Esempio 1: Massimizzare abbonamento → Backup economico
|
||||
|
||||
```
|
||||
Dashboard → Combo → Crea nuovo
|
||||
|
||||
Nome: premium-coding
|
||||
Modelli:
|
||||
1. cc/claude-opus-4-6 (Abbonamento principale)
|
||||
2. glm/glm-4.7 (Backup economico, $0.6/1M)
|
||||
3. minimax/MiniMax-M2.1 (Fallback più economico, $0.20/1M)
|
||||
|
||||
Usa nel CLI: premium-coding
|
||||
```
|
||||
|
||||
### Esempio 2: Solo gratuiti (Costo zero)
|
||||
|
||||
```
|
||||
Nome: free-combo
|
||||
Modelli:
|
||||
1. gc/gemini-3-flash-preview (180K gratis/mese)
|
||||
2. if/kimi-k2-thinking (illimitato)
|
||||
3. qw/qwen3-coder-plus (illimitato)
|
||||
|
||||
Costo: $0 per sempre!
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>🔧 Integrazione CLI</b></summary>
|
||||
|
||||
### Cursor IDE
|
||||
|
||||
```
|
||||
Impostazioni → Modelli → Avanzato:
|
||||
OpenAI API Base URL: http://localhost:20128/v1
|
||||
OpenAI API Key: [dalla dashboard OmniRoute]
|
||||
Model: cc/claude-opus-4-6
|
||||
```
|
||||
|
||||
### Claude Code
|
||||
|
||||
Usa la pagina **CLI Tools** nella dashboard per la configurazione con un clic, o modifica `~/.claude/settings.json` manualmente.
|
||||
|
||||
### Codex CLI
|
||||
|
||||
```bash
|
||||
export OPENAI_BASE_URL="http://localhost:20128"
|
||||
export OPENAI_API_KEY="your-omniroute-api-key"
|
||||
|
||||
codex "your prompt"
|
||||
```
|
||||
|
||||
### OpenClaw
|
||||
|
||||
**Opzione 1 — Dashboard (consigliato):**
|
||||
|
||||
```
|
||||
Dashboard → CLI Tools → OpenClaw → Seleziona Modello → Applica
|
||||
```
|
||||
|
||||
**Opzione 2 — Manuale:** Modifica `~/.openclaw/openclaw.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"models": {
|
||||
"providers": {
|
||||
"omniroute": {
|
||||
"baseUrl": "http://127.0.0.1:20128/v1",
|
||||
"apiKey": "sk_omniroute",
|
||||
"api": "openai-completions"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> **Nota:** OpenClaw funziona solo con OmniRoute locale. Usa `127.0.0.1` invece di `localhost` per evitare problemi di risoluzione IPv6.
|
||||
|
||||
### Cline / Continue / RooCode
|
||||
|
||||
```
|
||||
Impostazioni → Configurazione API:
|
||||
Provider: OpenAI Compatible
|
||||
Base URL: http://localhost:20128/v1
|
||||
API Key: [dalla dashboard OmniRoute]
|
||||
Model: if/kimi-k2-thinking
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## 📊 Modelli Disponibili
|
||||
|
||||
<details>
|
||||
<summary><b>Vedi tutti i modelli disponibili</b></summary>
|
||||
|
||||
**Claude Code (`cc/`)** - Pro/Max:
|
||||
|
||||
- `cc/claude-opus-4-6`
|
||||
- `cc/claude-sonnet-4-5-20250929`
|
||||
- `cc/claude-haiku-4-5-20251001`
|
||||
|
||||
**Codex (`cx/`)** - Plus/Pro:
|
||||
|
||||
- `cx/gpt-5.2-codex`
|
||||
- `cx/gpt-5.1-codex-max`
|
||||
|
||||
**Gemini CLI (`gc/`)** - GRATUITO:
|
||||
|
||||
- `gc/gemini-3-flash-preview`
|
||||
- `gc/gemini-2.5-pro`
|
||||
|
||||
**GitHub Copilot (`gh/`)**:
|
||||
|
||||
- `gh/gpt-5`
|
||||
- `gh/claude-4.5-sonnet`
|
||||
|
||||
**NVIDIA NIM (`nvidia/`)** - Crediti GRATUITI:
|
||||
|
||||
- `nvidia/llama-3.3-70b-instruct`
|
||||
- `nvidia/mistral-7b-instruct`
|
||||
- 50+ modelli su [build.nvidia.com](https://build.nvidia.com)
|
||||
|
||||
**GLM (`glm/`)** - $0.6/1M:
|
||||
|
||||
- `glm/glm-4.7`
|
||||
|
||||
**MiniMax (`minimax/`)** - $0.2/1M:
|
||||
|
||||
- `minimax/MiniMax-M2.1`
|
||||
|
||||
**iFlow (`if/`)** - GRATUITO:
|
||||
|
||||
- `if/kimi-k2-thinking`
|
||||
- `if/qwen3-coder-plus`
|
||||
- `if/deepseek-r1`
|
||||
- `if/glm-4.7`
|
||||
- `if/minimax-m2`
|
||||
|
||||
**Qwen (`qw/`)** - GRATUITO:
|
||||
|
||||
- `qw/qwen3-coder-plus`
|
||||
- `qw/qwen3-coder-flash`
|
||||
|
||||
**Kiro (`kr/`)** - GRATUITO:
|
||||
|
||||
- `kr/claude-sonnet-4.5`
|
||||
- `kr/claude-haiku-4.5`
|
||||
|
||||
**OpenRouter (`or/`)** - 100+ modelli:
|
||||
|
||||
- `or/anthropic/claude-4-sonnet`
|
||||
- `or/google/gemini-2.5-pro`
|
||||
- Qualsiasi modello da [openrouter.ai/models](https://openrouter.ai/models)
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Valutazioni (Evals)
|
||||
|
||||
OmniRoute include un framework di valutazione integrato per testare la qualità delle risposte LLM contro un golden set. Accesso via **Analytics → Evals** nella dashboard.
|
||||
|
||||
### Golden Set integrato
|
||||
|
||||
Il "OmniRoute Golden Set" precaricato contiene 10 casi di test:
|
||||
|
||||
- Saluti, matematica, geografia, generazione codice
|
||||
- Conformità formato JSON, traduzione, markdown
|
||||
- Rifiuto sicurezza (contenuto nocivo), conteggio, logica booleana
|
||||
|
||||
### Strategie di valutazione
|
||||
|
||||
| Strategia | Descrizione | Esempio |
|
||||
| ---------- | ---------------------------------------------------------- | -------------------------------- |
|
||||
| `exact` | L'output deve corrispondere esattamente | `"4"` |
|
||||
| `contains` | L'output deve contenere la sottostringa (case-insensitive) | `"Paris"` |
|
||||
| `regex` | L'output deve corrispondere al pattern regex | `"1.*2.*3"` |
|
||||
| `custom` | Funzione JS personalizzata restituisce true/false | `(output) => output.length > 10` |
|
||||
|
||||
---
|
||||
|
||||
## 🐛 Risoluzione Problemi
|
||||
|
||||
<details>
|
||||
<summary><b>Clicca per espandere la guida alla risoluzione problemi</b></summary>
|
||||
|
||||
**"Language model did not provide messages"**
|
||||
|
||||
- Quota del provider esaurita → Controlla il tracker quote nella dashboard
|
||||
- Soluzione: Usa un combo con fallback o passa a un livello più economico
|
||||
|
||||
**Rate limiting**
|
||||
|
||||
- Quota abbonamento esaurita → Fallback a GLM/MiniMax
|
||||
- Aggiungi combo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
|
||||
|
||||
**Token OAuth scaduto**
|
||||
|
||||
- Rinnovato automaticamente da OmniRoute
|
||||
- Se il problema persiste: Dashboard → Provider → Riconnetti
|
||||
|
||||
**Costi elevati**
|
||||
|
||||
- Controlla le statistiche di utilizzo in Dashboard → Costi
|
||||
- Cambia il modello principale a GLM/MiniMax
|
||||
- Usa il livello gratuito (Gemini CLI, iFlow) per compiti non critici
|
||||
|
||||
**La dashboard si apre sulla porta sbagliata**
|
||||
|
||||
- Imposta `PORT=20128` e `NEXT_PUBLIC_BASE_URL=http://localhost:20128`
|
||||
|
||||
**Errori cloud sync**
|
||||
|
||||
- Verifica che `BASE_URL` punti alla tua istanza in esecuzione
|
||||
- Verifica che `CLOUD_URL` punti all'endpoint cloud previsto
|
||||
- Mantieni i valori `NEXT_PUBLIC_*` allineati con i valori del server
|
||||
|
||||
**Il primo login non funziona**
|
||||
|
||||
- Controlla `INITIAL_PASSWORD` nel `.env`
|
||||
- Se non impostata, la password predefinita è `123456`
|
||||
|
||||
**Nessun log delle richieste**
|
||||
|
||||
- Imposta `ENABLE_REQUEST_LOGS=true` nel `.env`
|
||||
|
||||
**Il test di connessione mostra "Invalid" per provider compatibili OpenAI**
|
||||
|
||||
- Molti provider non espongono l'endpoint `/models`
|
||||
- OmniRoute v0.9.0+ include validazione fallback tramite chat completions
|
||||
- Assicurati che la URL base includa il suffisso `/v1`
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Stack Tecnologico
|
||||
|
||||
- **Runtime**: Node.js 20+
|
||||
- **Linguaggio**: TypeScript 5.9 — **100% TypeScript** in `src/` e `open-sse/` (v0.9.0)
|
||||
- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4
|
||||
- **Database**: LowDB (JSON) + SQLite (stato dominio + log proxy)
|
||||
- **Streaming**: Server-Sent Events (SSE)
|
||||
- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys
|
||||
- **Testing**: Node.js test runner (368+ test unitari)
|
||||
- **CI/CD**: GitHub Actions (pubblicazione automatica npm + Docker Hub al rilascio)
|
||||
- **Sito Web**: [omniroute.online](https://omniroute.online)
|
||||
- **Pacchetto**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)
|
||||
- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)
|
||||
- **Resilienza**: Circuit breaker, backoff esponenziale, anti-thundering herd, TLS spoofing
|
||||
|
||||
---
|
||||
|
||||
## 📖 Documentazione
|
||||
|
||||
| Documento | Descrizione |
|
||||
| ----------------------------------------------- | -------------------------------------------------- |
|
||||
| [Guida Utente](docs/USER_GUIDE.md) | Provider, combo, integrazione CLI, deploy |
|
||||
| [Riferimento API](docs/API_REFERENCE.md) | Tutti gli endpoint con esempi |
|
||||
| [Risoluzione Problemi](docs/TROUBLESHOOTING.md) | Problemi comuni e soluzioni |
|
||||
| [Architettura](docs/ARCHITECTURE.md) | Architettura del sistema e dettagli interni |
|
||||
| [Come Contribuire](CONTRIBUTING.md) | Setup di sviluppo e linee guida |
|
||||
| [Spec OpenAPI](docs/openapi.yaml) | Specifica OpenAPI 3.0 |
|
||||
| [Politica di Sicurezza](SECURITY.md) | Segnalazione vulnerabilità e pratiche di sicurezza |
|
||||
|
||||
---
|
||||
|
||||
## 📧 Supporto
|
||||
|
||||
- **Sito Web**: [omniroute.online](https://omniroute.online)
|
||||
- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
|
||||
- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
|
||||
- **Progetto Originale**: [9router di decolua](https://github.com/decolua/9router)
|
||||
|
||||
---
|
||||
|
||||
## 👥 Contributori
|
||||
|
||||
[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
|
||||
|
||||
### Come Contribuire
|
||||
|
||||
1. Fai il fork del repository
|
||||
2. Crea il tuo branch di funzionalità (`git checkout -b feature/amazing-feature`)
|
||||
3. Fai il commit delle modifiche (`git commit -m 'Add amazing feature'`)
|
||||
4. Fai il push al branch (`git push origin feature/amazing-feature`)
|
||||
5. Apri una Pull Request
|
||||
|
||||
Consulta [CONTRIBUTING.md](CONTRIBUTING.md) per le linee guida dettagliate.
|
||||
|
||||
### Rilasciare una nuova versione
|
||||
|
||||
```bash
|
||||
# Crea un rilascio — la pubblicazione npm avviene automaticamente
|
||||
gh release create v0.9.0 --title "v0.9.0" --generate-notes
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Cronologia Stelle
|
||||
|
||||
<a href="https://star-history.com/#diegosouzapw/OmniRoute&Date">
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=diegosouzapw/OmniRoute&type=Date&theme=dark" />
|
||||
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=diegosouzapw/OmniRoute&type=Date" />
|
||||
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=diegosouzapw/OmniRoute&type=Date" />
|
||||
</picture>
|
||||
</a>
|
||||
|
||||
---
|
||||
|
||||
## 🙏 Ringraziamenti
|
||||
|
||||
Un ringraziamento speciale a **[9router](https://github.com/decolua/9router)** di **[decolua](https://github.com/decolua)** — il progetto originale che ha ispirato questo fork. OmniRoute si costruisce su quell'incredibile base con funzionalità aggiuntive, API multi-modali e una riscrittura completa in TypeScript.
|
||||
|
||||
Un ringraziamento speciale a **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — l'implementazione originale in Go che ha ispirato questo porting in JavaScript.
|
||||
|
||||
---
|
||||
|
||||
## 📄 Licenza
|
||||
|
||||
Licenza MIT — vedi [LICENSE](LICENSE) per i dettagli.
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
<sub>Fatto con ❤️ per gli sviluppatori che programmano 24/7</sub>
|
||||
<br/>
|
||||
<sub><a href="https://omniroute.online">omniroute.online</a></sub>
|
||||
</div>
|
||||
1048
README.pt-BR.md
Normal file
1048
README.pt-BR.md
Normal file
File diff suppressed because it is too large
Load Diff
995
README.ru.md
Normal file
995
README.ru.md
Normal file
@@ -0,0 +1,995 @@
|
||||
<div align="center">
|
||||
<img src="./images/omniroute.png" alt="OmniRoute Dashboard" width="800"/>
|
||||
|
||||
# 🚀 OmniRoute — Бесплатный AI Gateway
|
||||
|
||||
### Никогда не прекращайте программировать. Умная маршрутизация к **БЕСПЛАТНЫМ и дешёвым AI-моделям** с автоматическим fallback.
|
||||
|
||||
_Ваш универсальный API-прокси — одна точка доступа, 36+ провайдеров, нулевой простой._
|
||||
|
||||
**Chat Completions • Embeddings • Генерация изображений • Аудио • Reranking • 100% TypeScript**
|
||||
|
||||
---
|
||||
|
||||
### 🤖 Бесплатный AI-провайдер для ваших любимых агентов программирования
|
||||
|
||||
_Подключайте любую IDE или CLI-инструмент с AI через OmniRoute — бесплатный API gateway для неограниченного программирования._
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/cline/cline">
|
||||
<img src="./public/providers/openclaw.png" alt="OpenClaw" width="48"/><br/>
|
||||
<b>OpenClaw</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 205K</sub>
|
||||
</td>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/HKUDS/nanobot">
|
||||
<img src="./public/providers/nanobot.png" alt="NanoBot" width="48"/><br/>
|
||||
<b>NanoBot</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 20.9K</sub>
|
||||
</td>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/sipeed/picoclaw">
|
||||
<img src="./public/providers/picoclaw.jpg" alt="PicoClaw" width="48"/><br/>
|
||||
<b>PicoClaw</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 14.6K</sub>
|
||||
</td>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/zeroclaw-labs/zeroclaw">
|
||||
<img src="./public/providers/zeroclaw.png" alt="ZeroClaw" width="48"/><br/>
|
||||
<b>ZeroClaw</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 9.9K</sub>
|
||||
</td>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/nearai/ironclaw">
|
||||
<img src="./public/providers/ironclaw.png" alt="IronClaw" width="48"/><br/>
|
||||
<b>IronClaw</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 2.1K</sub>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/anomalyco/opencode">
|
||||
<img src="./public/providers/opencode.svg" alt="OpenCode" width="48"/><br/>
|
||||
<b>OpenCode</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 106K</sub>
|
||||
</td>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/openai/codex">
|
||||
<img src="./public/providers/codex.png" alt="Codex CLI" width="48"/><br/>
|
||||
<b>Codex CLI</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 60.8K</sub>
|
||||
</td>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/anthropics/claude-code">
|
||||
<img src="./public/providers/claude.png" alt="Claude Code" width="48"/><br/>
|
||||
<b>Claude Code</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 67.3K</sub>
|
||||
</td>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/google-gemini/gemini-cli">
|
||||
<img src="./public/providers/gemini-cli.png" alt="Gemini CLI" width="48"/><br/>
|
||||
<b>Gemini CLI</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 94.7K</sub>
|
||||
</td>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/Kilo-Org/kilocode">
|
||||
<img src="./public/providers/kilocode.png" alt="Kilo Code" width="48"/><br/>
|
||||
<b>Kilo Code</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 15.5K</sub>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<sub>📡 Все агенты подключаются через <code>http://localhost:20128/v1</code> или <code>http://cloud.omniroute.online/v1</code> — одна конфигурация, неограниченные модели и квота</sub>
|
||||
|
||||
---
|
||||
|
||||
[](https://www.npmjs.com/package/omniroute)
|
||||
[](https://hub.docker.com/r/diegosouzapw/omniroute)
|
||||
[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
|
||||
[](https://omniroute.online)
|
||||
|
||||
[🌐 Сайт](https://omniroute.online) • [🚀 Быстрый старт](#-быстрый-старт) • [💡 Функции](#-основные-функции) • [📖 Документация](#-документация) • [💰 Цены](#-обзор-цен)
|
||||
|
||||
🌐 **Доступно на:** [English](README.md) | [Português](README.pt-BR.md) | [Español](README.es.md) | [Русский](README.ru.md) | [中文](README.zh-CN.md) | [Deutsch](README.de.md) | [Français](README.fr.md) | [Italiano](README.it.md)
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## 🤔 Почему OmniRoute?
|
||||
|
||||
**Перестаньте тратить деньги и упираться в лимиты:**
|
||||
|
||||
- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> Квота подписки истекает неиспользованной каждый месяц
|
||||
- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> Лимиты скорости останавливают вас посреди программирования
|
||||
- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> Дорогие API ($20-50/месяц за провайдера)
|
||||
- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> Ручное переключение между провайдерами
|
||||
|
||||
**OmniRoute решает это:**
|
||||
|
||||
- ✅ **Максимизируйте подписки** — Отслеживайте квоты, используйте всё до сброса
|
||||
- ✅ **Автоматический fallback** — Подписка → API Key → Дешёвый → Бесплатный, нулевой простой
|
||||
- ✅ **Мульти-аккаунт** — Round-robin между аккаунтами каждого провайдера
|
||||
- ✅ **Универсальный** — Работает с Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, любым CLI-инструментом
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Как это работает
|
||||
|
||||
```
|
||||
┌─────────────┐
|
||||
│ Ваш CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)
|
||||
│ Tool │
|
||||
└──────┬──────┘
|
||||
│ http://localhost:20128/v1
|
||||
↓
|
||||
┌─────────────────────────────────────────┐
|
||||
│ OmniRoute (Умный маршрутизатор) │
|
||||
│ • Трансляция формата (OpenAI ↔ Claude) │
|
||||
│ • Отслеживание квот + Embeddings + Изображения │
|
||||
│ • Автообновление токенов │
|
||||
└──────┬──────────────────────────────────┘
|
||||
│
|
||||
├─→ [Tier 1: ПОДПИСКА] Claude Code, Codex, Gemini CLI
|
||||
│ ↓ квота исчерпана
|
||||
├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM и др.
|
||||
│ ↓ лимит бюджета
|
||||
├─→ [Tier 3: ДЕШЁВЫЙ] GLM ($0.6/1M), MiniMax ($0.2/1M)
|
||||
│ ↓ лимит бюджета
|
||||
└─→ [Tier 4: БЕСПЛАТНЫЙ] iFlow, Qwen, Kiro (неограниченно)
|
||||
|
||||
Результат: Никогда не прекращайте программировать, минимальные затраты
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚡ Быстрый старт
|
||||
|
||||
**1. Установите глобально:**
|
||||
|
||||
```bash
|
||||
npm install -g omniroute
|
||||
omniroute
|
||||
```
|
||||
|
||||
🎉 Dashboard открывается на `http://localhost:20128`
|
||||
|
||||
| Команда | Описание |
|
||||
| ----------------------- | ------------------------------------------ |
|
||||
| `omniroute` | Запустить сервер (порт по умолчанию 20128) |
|
||||
| `omniroute --port 3000` | Использовать другой порт |
|
||||
| `omniroute --no-open` | Не открывать браузер автоматически |
|
||||
| `omniroute --help` | Показать справку |
|
||||
|
||||
**2. Подключите БЕСПЛАТНОГО провайдера:**
|
||||
|
||||
Dashboard → Провайдеры → Подключить **Claude Code** или **Antigravity** → OAuth вход → Готово!
|
||||
|
||||
**3. Используйте в CLI-инструменте:**
|
||||
|
||||
```
|
||||
Claude Code/Codex/Gemini CLI/OpenClaw/Cursor/Cline Настройки:
|
||||
Endpoint: http://localhost:20128/v1
|
||||
API Key: [скопируйте из dashboard]
|
||||
Model: if/kimi-k2-thinking
|
||||
```
|
||||
|
||||
**Готово!** Начните программировать с БЕСПЛАТНЫМИ AI-моделями.
|
||||
|
||||
**Альтернатива — запуск из исходного кода:**
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
npm install
|
||||
PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🐳 Docker
|
||||
|
||||
OmniRoute доступен как публичный Docker-образ на [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
|
||||
|
||||
**Быстрый запуск:**
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
--name omniroute \
|
||||
--restart unless-stopped \
|
||||
-p 20128:20128 \
|
||||
-v omniroute-data:/app/data \
|
||||
diegosouzapw/omniroute:latest
|
||||
```
|
||||
|
||||
**С файлом окружения:**
|
||||
|
||||
```bash
|
||||
# Скопируйте и отредактируйте .env
|
||||
cp .env.example .env
|
||||
|
||||
docker run -d \
|
||||
--name omniroute \
|
||||
--restart unless-stopped \
|
||||
--env-file .env \
|
||||
-p 20128:20128 \
|
||||
-v omniroute-data:/app/data \
|
||||
diegosouzapw/omniroute:latest
|
||||
```
|
||||
|
||||
**Используя Docker Compose:**
|
||||
|
||||
```bash
|
||||
# Базовый профиль (без CLI-инструментов)
|
||||
docker compose --profile base up -d
|
||||
|
||||
# CLI-профиль (Claude Code, Codex, OpenClaw встроены)
|
||||
docker compose --profile cli up -d
|
||||
```
|
||||
|
||||
| Образ | Тег | Размер | Описание |
|
||||
| ------------------------ | -------- | ------ | -------------------------- |
|
||||
| `diegosouzapw/omniroute` | `latest` | ~250MB | Последний стабильный релиз |
|
||||
| `diegosouzapw/omniroute` | `0.9.0` | ~250MB | Текущая версия |
|
||||
|
||||
---
|
||||
|
||||
## 💰 Обзор цен
|
||||
|
||||
| Tier | Провайдер | Стоимость | Сброс квоты | Лучше всего для |
|
||||
| ----------------- | ----------------- | ----------------------------- | ------------------ | -------------------------------- |
|
||||
| **💳 ПОДПИСКА** | Claude Code (Pro) | $20/мес | 5ч + еженедельно | Уже подписан |
|
||||
| | Codex (Plus/Pro) | $20-200/мес | 5ч + еженедельно | Пользователи OpenAI |
|
||||
| | Gemini CLI | **БЕСПЛАТНО** | 180K/мес + 1K/день | Все! |
|
||||
| | GitHub Copilot | $10-19/мес | Ежемесячно | Пользователи GitHub |
|
||||
| **🔑 API KEY** | NVIDIA NIM | **БЕСПЛАТНО** (1000 кредитов) | Одноразово | Бесплатное тестирование |
|
||||
| | DeepSeek | По использованию | Нет | Лучшее соотношение цена/качество |
|
||||
| | Groq | Беспл. уровень + платный | Ограничено | Сверхбыстрый вывод |
|
||||
| | xAI (Grok) | По использованию | Нет | Модели Grok |
|
||||
| | Mistral | Беспл. уровень + платный | Ограничено | Европейский AI |
|
||||
| | OpenRouter | По использованию | Нет | 100+ моделей |
|
||||
| **💰 ДЕШЁВЫЙ** | GLM-4.7 | $0.6/1M | Ежедневно 10ч | Бюджетный бэкап |
|
||||
| | MiniMax M2.1 | $0.2/1M | 5ч ротация | Самый дешёвый вариант |
|
||||
| | Kimi K2 | $9/мес фикс | 10M токенов/мес | Предсказуемая цена |
|
||||
| **🆓 БЕСПЛАТНЫЙ** | iFlow | $0 | Неограниченно | 8 бесплатных моделей |
|
||||
| | Qwen | $0 | Неограниченно | 3 бесплатные модели |
|
||||
| | Kiro | $0 | Неограниченно | Claude бесплатно |
|
||||
|
||||
**💡 Совет:** Начните с Gemini CLI (180K бесплатно/мес) + iFlow (неограниченно бесплатно) = $0!
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Сценарии использования
|
||||
|
||||
### Сценарий 1: «У меня подписка Claude Pro»
|
||||
|
||||
**Проблема:** Квота истекает неиспользованной, лимиты скорости во время интенсивного программирования
|
||||
|
||||
```
|
||||
Combo: "maximize-claude"
|
||||
1. cc/claude-opus-4-6 (используйте подписку полностью)
|
||||
2. glm/glm-4.7 (дешёвый бэкап при исчерпании квоты)
|
||||
3. if/kimi-k2-thinking (бесплатный аварийный fallback)
|
||||
|
||||
Месячная стоимость: $20 (подписка) + ~$5 (бэкап) = $25 итого
|
||||
vs. $20 + упирание в лимиты = разочарование
|
||||
```
|
||||
|
||||
### Сценарий 2: «Хочу нулевую стоимость»
|
||||
|
||||
**Проблема:** Не может позволить подписки, нужен надёжный AI для программирования
|
||||
|
||||
```
|
||||
Combo: "free-forever"
|
||||
1. gc/gemini-3-flash (180K бесплатно/мес)
|
||||
2. if/kimi-k2-thinking (неограниченно бесплатно)
|
||||
3. qw/qwen3-coder-plus (неограниченно бесплатно)
|
||||
|
||||
Месячная стоимость: $0
|
||||
Качество: Модели готовые к продакшену
|
||||
```
|
||||
|
||||
### Сценарий 3: «Мне нужно программировать 24/7, без перерывов»
|
||||
|
||||
**Проблема:** Дедлайны, не может позволить простой
|
||||
|
||||
```
|
||||
Combo: "always-on"
|
||||
1. cc/claude-opus-4-6 (лучшее качество)
|
||||
2. cx/gpt-5.2-codex (вторая подписка)
|
||||
3. glm/glm-4.7 (дешёвый, ежедневный сброс)
|
||||
4. minimax/MiniMax-M2.1 (самый дешёвый, сброс 5ч)
|
||||
5. if/kimi-k2-thinking (бесплатно неограниченно)
|
||||
|
||||
Результат: 5 уровней fallback = нулевой простой
|
||||
```
|
||||
|
||||
### Сценарий 4: «Хочу БЕСПЛАТНЫЙ AI в OpenClaw»
|
||||
|
||||
**Проблема:** Нужен AI-ассистент в мессенджерах, полностью бесплатно
|
||||
|
||||
```
|
||||
Combo: "openclaw-free"
|
||||
1. if/glm-4.7 (неограниченно бесплатно)
|
||||
2. if/minimax-m2.1 (неограниченно бесплатно)
|
||||
3. if/kimi-k2-thinking (неограниченно бесплатно)
|
||||
|
||||
Месячная стоимость: $0
|
||||
Доступ через: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 💡 Основные функции
|
||||
|
||||
### 🧠 Маршрутизация и интеллект
|
||||
|
||||
| Функция | Что делает |
|
||||
| ------------------------------------------- | ----------------------------------------------------------------------------- |
|
||||
| 🎯 **Умный 4-уровневый Fallback** | Авто-маршрутизация: Подписка → API Key → Дешёвый → Бесплатный |
|
||||
| 📊 **Отслеживание квот в реальном времени** | Счётчик токенов в реальном времени + обратный отсчёт до сброса |
|
||||
| 🔄 **Трансляция формата** | OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro бесшовно |
|
||||
| 👥 **Мульти-аккаунт** | Несколько аккаунтов на провайдера с интеллектуальным выбором |
|
||||
| 🔄 **Автообновление токенов** | OAuth-токены обновляются автоматически с повторами |
|
||||
| 🎨 **Пользовательские комбо** | 6 стратегий: fill-first, round-robin, p2c, random, least-used, cost-optimized |
|
||||
| 🧩 **Пользовательские модели** | Добавьте любой ID модели к любому провайдеру |
|
||||
| 🌐 **Wildcard-маршрутизатор** | Маршрутизируйте паттерны `provider/*` к любому провайдеру динамически |
|
||||
| 🧠 **Бюджет рассуждений** | Режимы passthrough, auto, custom и adaptive для моделей рассуждений |
|
||||
| 💬 **Инъекция System Prompt** | Глобальный system prompt для всех запросов |
|
||||
| 📄 **API Responses** | Полная поддержка OpenAI Responses API (`/v1/responses`) для Codex |
|
||||
|
||||
### 🎵 Мультимодальные API
|
||||
|
||||
| Функция | Что делает |
|
||||
| ---------------------------- | --------------------------------------------------- |
|
||||
| 🖼️ **Генерация изображений** | `/v1/images/generations` — 4 провайдера, 9+ моделей |
|
||||
| 📐 **Embeddings** | `/v1/embeddings` — 6 провайдеров, 9+ моделей |
|
||||
| 🎤 **Транскрипция аудио** | `/v1/audio/transcriptions` — Совместимо с Whisper |
|
||||
| 🔊 **Текст в речь** | `/v1/audio/speech` — Мульти-провайдерный синтез |
|
||||
| 🛡️ **Модерация** | `/v1/moderations` — Проверки безопасности контента |
|
||||
| 🔀 **Reranking** | `/v1/rerank` — Переранжирование релевантности |
|
||||
|
||||
### 🛡️ Устойчивость и безопасность
|
||||
|
||||
| Функция | Что делает |
|
||||
| -------------------------------- | -------------------------------------------------------------- |
|
||||
| 🔌 **Circuit Breaker** | Авто-открытие/закрытие по провайдеру с настраиваемыми порогами |
|
||||
| 🛡️ **Anti-Thundering Herd** | Mutex + семафор для API key провайдеров |
|
||||
| 🧠 **Семантический кеш** | Двухуровневый кеш (сигнатура + семантика) снижает стоимость |
|
||||
| ⚡ **Идемпотентность запросов** | 5с окно дедупликации для дублирующихся запросов |
|
||||
| 🔒 **Спуфинг TLS Fingerprint** | Обход обнаружения ботов через wreq-js |
|
||||
| 🌐 **Фильтрация IP** | Allowlist/blocklist для контроля доступа к API |
|
||||
| 📊 **Настраиваемые Rate Limits** | Настраиваемые RPM, минимальный интервал, макс. конкуррентность |
|
||||
|
||||
### 📊 Наблюдаемость и аналитика
|
||||
|
||||
| Функция | Что делает |
|
||||
| ----------------------------- | ------------------------------------------------------------------------ |
|
||||
| 📝 **Логи запросов** | Режим debug с полными логами запросов/ответов |
|
||||
| 💾 **Логи SQLite** | Постоянные proxy-логи переживают перезапуски |
|
||||
| 📊 **Dashboard аналитики** | Recharts: карточки статистики, график использования, таблица провайдеров |
|
||||
| 📈 **Отслеживание прогресса** | Opt-in SSE-события прогресса для стриминга |
|
||||
| 🧪 **Оценки LLM** | Тестирование с golden set и 4 стратегиями сравнения |
|
||||
| 🔍 **Телеметрия запросов** | Агрегация латентности p50/p95/p99 + трекинг X-Request-Id |
|
||||
| 📋 **Логи + Квоты** | Отдельные страницы для просмотра логов и отслеживания квот |
|
||||
| 🏥 **Dashboard здоровья** | Uptime, состояния circuit breaker, блокировки, статистика кеша |
|
||||
| 💰 **Отслеживание стоимости** | Управление бюджетом + настройка цен по моделям |
|
||||
|
||||
### ☁️ Деплой и синхронизация
|
||||
|
||||
| Функция | Что делает |
|
||||
| -------------------------- | --------------------------------------------------------------------------- |
|
||||
| 💾 **Cloud Sync** | Синхронизация настроек между устройствами через Cloudflare Workers |
|
||||
| 🌐 **Деплой куда угодно** | Localhost, VPS, Docker, Cloudflare Workers |
|
||||
| 🔑 **Управление API Keys** | Генерация, ротация и настройка scope API keys по провайдерам |
|
||||
| 🧙 **Мастер настройки** | 4-шаговая настройка для новых пользователей |
|
||||
| 🔧 **Dashboard CLI Tools** | Настройка в один клик для Claude, Codex, Cline, OpenClaw, Kilo, Antigravity |
|
||||
| 🔄 **Бэкапы БД** | Автоматическое резервное копирование и восстановление всех настроек |
|
||||
|
||||
<details>
|
||||
<summary><b>📖 Подробности функций</b></summary>
|
||||
|
||||
### 🎯 Умный 4-уровневый Fallback
|
||||
|
||||
Создавайте комбо с автоматическим fallback:
|
||||
|
||||
```
|
||||
Combo: "my-coding-stack"
|
||||
1. cc/claude-opus-4-6 (ваша подписка)
|
||||
2. nvidia/llama-3.3-70b (бесплатный NVIDIA API)
|
||||
3. glm/glm-4.7 (дешёвый бэкап, $0.6/1M)
|
||||
4. if/kimi-k2-thinking (бесплатный fallback)
|
||||
|
||||
→ Автоматически переключается при исчерпании квоты или ошибках
|
||||
```
|
||||
|
||||
### 📊 Отслеживание квот в реальном времени
|
||||
|
||||
- Потребление токенов по провайдерам
|
||||
- Обратный отсчёт до сброса (5 часов, ежедневно, еженедельно)
|
||||
- Оценка стоимости для платных уровней
|
||||
- Ежемесячные отчёты о расходах
|
||||
|
||||
### 🔄 Трансляция формата
|
||||
|
||||
Бесшовная трансляция между форматами:
|
||||
|
||||
- **OpenAI** ↔ **Claude** ↔ **Gemini** ↔ **OpenAI Responses**
|
||||
- Ваш CLI отправляет формат OpenAI → OmniRoute транслирует → Провайдер получает нативный формат
|
||||
- Работает с любым инструментом, поддерживающим пользовательские OpenAI endpoints
|
||||
|
||||
### 👥 Мульти-аккаунт
|
||||
|
||||
- Добавляйте несколько аккаунтов на провайдера
|
||||
- Автоматический round-robin или маршрутизация по приоритету
|
||||
- Fallback на следующий аккаунт при исчерпании квоты
|
||||
|
||||
### 🔄 Автообновление токенов
|
||||
|
||||
- OAuth-токены обновляются автоматически до истечения
|
||||
- Без необходимости ручной повторной аутентификации
|
||||
- Бесшовный опыт по всем провайдерам
|
||||
|
||||
### 🎨 Пользовательские комбо
|
||||
|
||||
- Создавайте неограниченные комбинации моделей
|
||||
- 6 стратегий: fill-first, round-robin, power-of-two-choices, random, least-used, cost-optimized
|
||||
- Делитесь комбо между устройствами с Cloud Sync
|
||||
|
||||
### 🏥 Dashboard здоровья
|
||||
|
||||
- Статус системы (uptime, версия, использование памяти)
|
||||
- Состояния circuit breaker по провайдерам (Closed/Open/Half-Open)
|
||||
- Статус rate limit и активные блокировки
|
||||
- Статистика кеша сигнатур
|
||||
- Телеметрия латентности (p50/p95/p99) + кеш промптов
|
||||
- Сброс состояния здоровья одним кликом
|
||||
|
||||
### 🔧 Playground транслятора
|
||||
|
||||
- Отладка, тестирование и визуализация трансляции форматов API
|
||||
- Отправляйте запросы и смотрите, как OmniRoute транслирует между форматами провайдеров
|
||||
- Бесценно для устранения проблем интеграции
|
||||
|
||||
### 💾 Cloud Sync
|
||||
|
||||
- Синхронизация провайдеров, комбо и настроек между устройствами
|
||||
- Автоматическая фоновая синхронизация
|
||||
- Безопасное шифрованное хранилище
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## 📖 Руководство по настройке
|
||||
|
||||
<details>
|
||||
<summary><b>💳 Провайдеры по подписке</b></summary>
|
||||
|
||||
### Claude Code (Pro/Max)
|
||||
|
||||
```bash
|
||||
Dashboard → Провайдеры → Подключить Claude Code
|
||||
→ OAuth вход → Автообновление токенов
|
||||
→ Отслеживание квоты 5ч + еженедельно
|
||||
|
||||
Модели:
|
||||
cc/claude-opus-4-6
|
||||
cc/claude-sonnet-4-5-20250929
|
||||
cc/claude-haiku-4-5-20251001
|
||||
```
|
||||
|
||||
**Совет:** Используйте Opus для сложных задач, Sonnet для скорости. OmniRoute отслеживает квоту по моделям!
|
||||
|
||||
### OpenAI Codex (Plus/Pro)
|
||||
|
||||
```bash
|
||||
Dashboard → Провайдеры → Подключить Codex
|
||||
→ OAuth вход (порт 1455)
|
||||
→ Сброс 5ч + еженедельно
|
||||
|
||||
Модели:
|
||||
cx/gpt-5.2-codex
|
||||
cx/gpt-5.1-codex-max
|
||||
```
|
||||
|
||||
### Gemini CLI (БЕСПЛАТНО 180K/мес!)
|
||||
|
||||
```bash
|
||||
Dashboard → Провайдеры → Подключить Gemini CLI
|
||||
→ Google OAuth
|
||||
→ 180K completions/мес + 1K/день
|
||||
|
||||
Модели:
|
||||
gc/gemini-3-flash-preview
|
||||
gc/gemini-2.5-pro
|
||||
```
|
||||
|
||||
**Лучшая ценность:** Огромный бесплатный уровень! Используйте перед платными.
|
||||
|
||||
### GitHub Copilot
|
||||
|
||||
```bash
|
||||
Dashboard → Провайдеры → Подключить GitHub
|
||||
→ OAuth через GitHub
|
||||
→ Ежемесячный сброс (1-е число)
|
||||
|
||||
Модели:
|
||||
gh/gpt-5
|
||||
gh/claude-4.5-sonnet
|
||||
gh/gemini-3-pro
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>🔑 Провайдеры по API Key</b></summary>
|
||||
|
||||
### NVIDIA NIM (БЕСПЛАТНО 1000 кредитов!)
|
||||
|
||||
1. Регистрация: [build.nvidia.com](https://build.nvidia.com)
|
||||
2. Получите бесплатный API key (1000 кредитов включены)
|
||||
3. Dashboard → Добавить провайдера → NVIDIA NIM:
|
||||
- API Key: `nvapi-your-key`
|
||||
|
||||
**Модели:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct` и 50+ других
|
||||
|
||||
**Совет:** OpenAI-совместимый API — работает идеально с трансляцией форматов OmniRoute!
|
||||
|
||||
### DeepSeek
|
||||
|
||||
1. Регистрация: [platform.deepseek.com](https://platform.deepseek.com)
|
||||
2. Получите API key
|
||||
3. Dashboard → Добавить провайдера → DeepSeek
|
||||
|
||||
**Модели:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`
|
||||
|
||||
### Groq (Бесплатный уровень доступен!)
|
||||
|
||||
1. Регистрация: [console.groq.com](https://console.groq.com)
|
||||
2. Получите API key (бесплатный уровень включён)
|
||||
3. Dashboard → Добавить провайдера → Groq
|
||||
|
||||
**Модели:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`
|
||||
|
||||
**Совет:** Сверхбыстрый вывод — лучший для программирования в реальном времени!
|
||||
|
||||
### OpenRouter (100+ моделей)
|
||||
|
||||
1. Регистрация: [openrouter.ai](https://openrouter.ai)
|
||||
2. Получите API key
|
||||
3. Dashboard → Добавить провайдера → OpenRouter
|
||||
|
||||
**Модели:** Доступ к 100+ моделям от всех основных провайдеров через один API key.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>💰 Дешёвые провайдеры (Бэкап)</b></summary>
|
||||
|
||||
### GLM-4.7 (Ежедневный сброс, $0.6/1M)
|
||||
|
||||
1. Регистрация: [Zhipu AI](https://open.bigmodel.cn/)
|
||||
2. Получите API key из Coding Plan
|
||||
3. Dashboard → Добавить API Key:
|
||||
- Провайдер: `glm`
|
||||
- API Key: `your-key`
|
||||
|
||||
**Используйте:** `glm/glm-4.7`
|
||||
|
||||
**Совет:** Coding Plan предлагает 3× квоту по цене 1/7! Ежедневный сброс в 10:00.
|
||||
|
||||
### MiniMax M2.1 (Сброс 5ч, $0.20/1M)
|
||||
|
||||
1. Регистрация: [MiniMax](https://www.minimax.io/)
|
||||
2. Получите API key
|
||||
3. Dashboard → Добавить API Key
|
||||
|
||||
**Используйте:** `minimax/MiniMax-M2.1`
|
||||
|
||||
**Совет:** Самый дешёвый вариант для длинного контекста (1M токенов)!
|
||||
|
||||
### Kimi K2 ($9/мес фикс)
|
||||
|
||||
1. Подпишитесь: [Moonshot AI](https://platform.moonshot.ai/)
|
||||
2. Получите API key
|
||||
3. Dashboard → Добавить API Key
|
||||
|
||||
**Используйте:** `kimi/kimi-latest`
|
||||
|
||||
**Совет:** Фикс $9/мес за 10M токенов = $0.90/1M эффективная стоимость!
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>🆓 БЕСПЛАТНЫЕ провайдеры (Аварийный бэкап)</b></summary>
|
||||
|
||||
### iFlow (8 БЕСПЛАТНЫХ моделей)
|
||||
|
||||
```bash
|
||||
Dashboard → Подключить iFlow
|
||||
→ OAuth вход iFlow
|
||||
→ Неограниченное использование
|
||||
|
||||
Модели:
|
||||
if/kimi-k2-thinking
|
||||
if/qwen3-coder-plus
|
||||
if/glm-4.7
|
||||
if/minimax-m2
|
||||
if/deepseek-r1
|
||||
```
|
||||
|
||||
### Qwen (3 БЕСПЛАТНЫЕ модели)
|
||||
|
||||
```bash
|
||||
Dashboard → Подключить Qwen
|
||||
→ Авторизация по коду устройства
|
||||
→ Неограниченное использование
|
||||
|
||||
Модели:
|
||||
qw/qwen3-coder-plus
|
||||
qw/qwen3-coder-flash
|
||||
```
|
||||
|
||||
### Kiro (Claude БЕСПЛАТНО)
|
||||
|
||||
```bash
|
||||
Dashboard → Подключить Kiro
|
||||
→ AWS Builder ID или Google/GitHub
|
||||
→ Неограниченное использование
|
||||
|
||||
Модели:
|
||||
kr/claude-sonnet-4.5
|
||||
kr/claude-haiku-4.5
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>🎨 Создание комбо</b></summary>
|
||||
|
||||
### Пример 1: Максимизация подписки → Дешёвый бэкап
|
||||
|
||||
```
|
||||
Dashboard → Комбо → Создать новое
|
||||
|
||||
Название: premium-coding
|
||||
Модели:
|
||||
1. cc/claude-opus-4-6 (Основная подписка)
|
||||
2. glm/glm-4.7 (Дешёвый бэкап, $0.6/1M)
|
||||
3. minimax/MiniMax-M2.1 (Самый дешёвый fallback, $0.20/1M)
|
||||
|
||||
Используйте в CLI: premium-coding
|
||||
```
|
||||
|
||||
### Пример 2: Только бесплатные (Нулевая стоимость)
|
||||
|
||||
```
|
||||
Название: free-combo
|
||||
Модели:
|
||||
1. gc/gemini-3-flash-preview (180K бесплатно/мес)
|
||||
2. if/kimi-k2-thinking (неограниченно)
|
||||
3. qw/qwen3-coder-plus (неограниченно)
|
||||
|
||||
Стоимость: $0 навсегда!
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>🔧 Интеграция с CLI</b></summary>
|
||||
|
||||
### Cursor IDE
|
||||
|
||||
```
|
||||
Настройки → Модели → Расширенные:
|
||||
OpenAI API Base URL: http://localhost:20128/v1
|
||||
OpenAI API Key: [из dashboard OmniRoute]
|
||||
Model: cc/claude-opus-4-6
|
||||
```
|
||||
|
||||
### Claude Code
|
||||
|
||||
Используйте страницу **CLI Tools** в dashboard для настройки в один клик, или редактируйте `~/.claude/settings.json` вручную.
|
||||
|
||||
### Codex CLI
|
||||
|
||||
```bash
|
||||
export OPENAI_BASE_URL="http://localhost:20128"
|
||||
export OPENAI_API_KEY="your-omniroute-api-key"
|
||||
|
||||
codex "your prompt"
|
||||
```
|
||||
|
||||
### OpenClaw
|
||||
|
||||
**Вариант 1 — Dashboard (рекомендуется):**
|
||||
|
||||
```
|
||||
Dashboard → CLI Tools → OpenClaw → Выбрать модель → Применить
|
||||
```
|
||||
|
||||
**Вариант 2 — Вручную:** Редактируйте `~/.openclaw/openclaw.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"models": {
|
||||
"providers": {
|
||||
"omniroute": {
|
||||
"baseUrl": "http://127.0.0.1:20128/v1",
|
||||
"apiKey": "sk_omniroute",
|
||||
"api": "openai-completions"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> **Примечание:** OpenClaw работает только с локальным OmniRoute. Используйте `127.0.0.1` вместо `localhost` для избежания проблем с IPv6.
|
||||
|
||||
### Cline / Continue / RooCode
|
||||
|
||||
```
|
||||
Настройки → Конфигурация API:
|
||||
Провайдер: OpenAI Compatible
|
||||
Base URL: http://localhost:20128/v1
|
||||
API Key: [из dashboard OmniRoute]
|
||||
Model: if/kimi-k2-thinking
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## 📊 Доступные модели
|
||||
|
||||
<details>
|
||||
<summary><b>Посмотреть все доступные модели</b></summary>
|
||||
|
||||
**Claude Code (`cc/`)** - Pro/Max:
|
||||
|
||||
- `cc/claude-opus-4-6`
|
||||
- `cc/claude-sonnet-4-5-20250929`
|
||||
- `cc/claude-haiku-4-5-20251001`
|
||||
|
||||
**Codex (`cx/`)** - Plus/Pro:
|
||||
|
||||
- `cx/gpt-5.2-codex`
|
||||
- `cx/gpt-5.1-codex-max`
|
||||
|
||||
**Gemini CLI (`gc/`)** - БЕСПЛАТНО:
|
||||
|
||||
- `gc/gemini-3-flash-preview`
|
||||
- `gc/gemini-2.5-pro`
|
||||
|
||||
**GitHub Copilot (`gh/`)**:
|
||||
|
||||
- `gh/gpt-5`
|
||||
- `gh/claude-4.5-sonnet`
|
||||
|
||||
**NVIDIA NIM (`nvidia/`)** - БЕСПЛАТНЫЕ кредиты:
|
||||
|
||||
- `nvidia/llama-3.3-70b-instruct`
|
||||
- `nvidia/mistral-7b-instruct`
|
||||
- 50+ моделей на [build.nvidia.com](https://build.nvidia.com)
|
||||
|
||||
**GLM (`glm/`)** - $0.6/1M:
|
||||
|
||||
- `glm/glm-4.7`
|
||||
|
||||
**MiniMax (`minimax/`)** - $0.2/1M:
|
||||
|
||||
- `minimax/MiniMax-M2.1`
|
||||
|
||||
**iFlow (`if/`)** - БЕСПЛАТНО:
|
||||
|
||||
- `if/kimi-k2-thinking`
|
||||
- `if/qwen3-coder-plus`
|
||||
- `if/deepseek-r1`
|
||||
- `if/glm-4.7`
|
||||
- `if/minimax-m2`
|
||||
|
||||
**Qwen (`qw/`)** - БЕСПЛАТНО:
|
||||
|
||||
- `qw/qwen3-coder-plus`
|
||||
- `qw/qwen3-coder-flash`
|
||||
|
||||
**Kiro (`kr/`)** - БЕСПЛАТНО:
|
||||
|
||||
- `kr/claude-sonnet-4.5`
|
||||
- `kr/claude-haiku-4.5`
|
||||
|
||||
**OpenRouter (`or/`)** - 100+ моделей:
|
||||
|
||||
- `or/anthropic/claude-4-sonnet`
|
||||
- `or/google/gemini-2.5-pro`
|
||||
- Любая модель с [openrouter.ai/models](https://openrouter.ai/models)
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Оценки (Evals)
|
||||
|
||||
OmniRoute включает встроенный фреймворк оценки для тестирования качества ответов LLM по golden set. Доступ через **Analytics → Evals** в dashboard.
|
||||
|
||||
### Встроенный Golden Set
|
||||
|
||||
Предзагруженный «OmniRoute Golden Set» содержит 10 тестов:
|
||||
|
||||
- Приветствия, математика, география, генерация кода
|
||||
- Соответствие формату JSON, перевод, markdown
|
||||
- Отказ от небезопасного контента, подсчёт, булева логика
|
||||
|
||||
### Стратегии оценки
|
||||
|
||||
| Стратегия | Описание | Пример |
|
||||
| ---------- | ----------------------------------------------------- | -------------------------------- |
|
||||
| `exact` | Вывод должен совпадать точно | `"4"` |
|
||||
| `contains` | Вывод должен содержать подстроку (без учёта регистра) | `"Paris"` |
|
||||
| `regex` | Вывод должен соответствовать regex-паттерну | `"1.*2.*3"` |
|
||||
| `custom` | Пользовательская JS-функция возвращает true/false | `(output) => output.length > 10` |
|
||||
|
||||
---
|
||||
|
||||
## 🐛 Устранение неполадок
|
||||
|
||||
<details>
|
||||
<summary><b>Нажмите для раскрытия руководства</b></summary>
|
||||
|
||||
**«Language model did not provide messages»**
|
||||
|
||||
- Квота провайдера исчерпана → Проверьте трекер квот в dashboard
|
||||
- Решение: Используйте комбо с fallback или переключитесь на более дешёвый уровень
|
||||
|
||||
**Rate limiting**
|
||||
|
||||
- Квота подписки исчерпана → Fallback на GLM/MiniMax
|
||||
- Добавьте комбо: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
|
||||
|
||||
**OAuth-токен истёк**
|
||||
|
||||
- Обновляется автоматически OmniRoute
|
||||
- Если проблема сохраняется: Dashboard → Провайдер → Переподключить
|
||||
|
||||
**Высокие расходы**
|
||||
|
||||
- Проверьте статистику в Dashboard → Расходы
|
||||
- Переключите основную модель на GLM/MiniMax
|
||||
- Используйте бесплатный уровень (Gemini CLI, iFlow) для некритичных задач
|
||||
|
||||
**Dashboard открывается на неправильном порту**
|
||||
|
||||
- Установите `PORT=20128` и `NEXT_PUBLIC_BASE_URL=http://localhost:20128`
|
||||
|
||||
**Ошибки cloud sync**
|
||||
|
||||
- Проверьте что `BASE_URL` указывает на ваш запущенный экземпляр
|
||||
- Проверьте что `CLOUD_URL` указывает на правильный облачный endpoint
|
||||
- Держите значения `NEXT_PUBLIC_*` синхронизированными с серверными значениями
|
||||
|
||||
**Первый вход не работает**
|
||||
|
||||
- Проверьте `INITIAL_PASSWORD` в `.env`
|
||||
- Если не задан, пароль по умолчанию `123456`
|
||||
|
||||
**Нет логов запросов**
|
||||
|
||||
- Установите `ENABLE_REQUEST_LOGS=true` в `.env`
|
||||
|
||||
**Тест подключения показывает «Invalid» для OpenAI-совместимых провайдеров**
|
||||
|
||||
- Многие провайдеры не предоставляют endpoint `/models`
|
||||
- OmniRoute v0.9.0+ включает fallback-валидацию через chat completions
|
||||
- Убедитесь что base URL содержит суффикс `/v1`
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Технологический стек
|
||||
|
||||
- **Runtime**: Node.js 20+
|
||||
- **Язык**: TypeScript 5.9 — **100% TypeScript** в `src/` и `open-sse/` (v0.9.0)
|
||||
- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4
|
||||
- **База данных**: LowDB (JSON) + SQLite (состояние домена + proxy-логи)
|
||||
- **Стриминг**: Server-Sent Events (SSE)
|
||||
- **Аутентификация**: OAuth 2.0 (PKCE) + JWT + API Keys
|
||||
- **Тестирование**: Node.js test runner (368+ юнит-тестов)
|
||||
- **CI/CD**: GitHub Actions (авто-публикация npm + Docker Hub при релизе)
|
||||
- **Сайт**: [omniroute.online](https://omniroute.online)
|
||||
- **Пакет**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)
|
||||
- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)
|
||||
- **Устойчивость**: Circuit breaker, экспоненциальный backoff, anti-thundering herd, TLS-спуфинг
|
||||
|
||||
---
|
||||
|
||||
## 📖 Документация
|
||||
|
||||
| Документ | Описание |
|
||||
| ----------------------------------------------- | ------------------------------------------------ |
|
||||
| [Руководство пользователя](docs/USER_GUIDE.md) | Провайдеры, комбо, интеграция CLI, деплой |
|
||||
| [Справка API](docs/API_REFERENCE.md) | Все endpoints с примерами |
|
||||
| [Устранение неполадок](docs/TROUBLESHOOTING.md) | Частые проблемы и решения |
|
||||
| [Архитектура](docs/ARCHITECTURE.md) | Архитектура системы и внутреннее устройство |
|
||||
| [Как внести вклад](CONTRIBUTING.md) | Настройка разработки и руководящие принципы |
|
||||
| [Спецификация OpenAPI](docs/openapi.yaml) | Спецификация OpenAPI 3.0 |
|
||||
| [Политика безопасности](SECURITY.md) | Сообщение об уязвимостях и практики безопасности |
|
||||
|
||||
---
|
||||
|
||||
## 📧 Поддержка
|
||||
|
||||
- **Сайт**: [omniroute.online](https://omniroute.online)
|
||||
- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
|
||||
- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
|
||||
- **Оригинальный проект**: [9router от decolua](https://github.com/decolua/9router)
|
||||
|
||||
---
|
||||
|
||||
## 👥 Участники
|
||||
|
||||
[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
|
||||
|
||||
### Как внести вклад
|
||||
|
||||
1. Сделайте fork репозитория
|
||||
2. Создайте ветку функции (`git checkout -b feature/amazing-feature`)
|
||||
3. Зафиксируйте изменения (`git commit -m 'Add amazing feature'`)
|
||||
4. Отправьте в ветку (`git push origin feature/amazing-feature`)
|
||||
5. Откройте Pull Request
|
||||
|
||||
См. [CONTRIBUTING.md](CONTRIBUTING.md) для подробных рекомендаций.
|
||||
|
||||
### Выпуск новой версии
|
||||
|
||||
```bash
|
||||
# Создайте релиз — публикация в npm происходит автоматически
|
||||
gh release create v0.9.0 --title "v0.9.0" --generate-notes
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 История звёзд
|
||||
|
||||
<a href="https://star-history.com/#diegosouzapw/OmniRoute&Date">
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=diegosouzapw/OmniRoute&type=Date&theme=dark" />
|
||||
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=diegosouzapw/OmniRoute&type=Date" />
|
||||
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=diegosouzapw/OmniRoute&type=Date" />
|
||||
</picture>
|
||||
</a>
|
||||
|
||||
---
|
||||
|
||||
## 🙏 Благодарности
|
||||
|
||||
Особая благодарность **[9router](https://github.com/decolua/9router)** от **[decolua](https://github.com/decolua)** — оригинальному проекту, вдохновившему этот форк. OmniRoute строится на этом невероятном фундаменте с дополнительными функциями, мультимодальными API и полной переписью на TypeScript.
|
||||
|
||||
Особая благодарность **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — оригинальной реализации на Go, вдохновившей этот порт на JavaScript.
|
||||
|
||||
---
|
||||
|
||||
## 📄 Лицензия
|
||||
|
||||
Лицензия MIT — см. [LICENSE](LICENSE) для подробностей.
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
<sub>Сделано с ❤️ для разработчиков, которые программируют 24/7</sub>
|
||||
<br/>
|
||||
<sub><a href="https://omniroute.online">omniroute.online</a></sub>
|
||||
</div>
|
||||
995
README.zh-CN.md
Normal file
995
README.zh-CN.md
Normal file
@@ -0,0 +1,995 @@
|
||||
<div align="center">
|
||||
<img src="./images/omniroute.png" alt="OmniRoute Dashboard" width="800"/>
|
||||
|
||||
# 🚀 OmniRoute — 免费 AI 网关
|
||||
|
||||
### 永不停止编程。智能路由至**免费和低成本 AI 模型**，自动故障转移。
|
||||
|
||||
_您的通用 API 代理 — 一个端点，36+ 提供商，零停机时间。_
|
||||
|
||||
**Chat Completions • Embeddings • 图像生成 • 音频 • Reranking • 100% TypeScript**
|
||||
|
||||
---
|
||||
|
||||
### 🤖 为您最爱的编程代理提供免费 AI
|
||||
|
||||
_通过 OmniRoute 连接任何 AI 驱动的 IDE 或 CLI 工具 — 免费 API 网关，无限编程。_
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/cline/cline">
|
||||
<img src="./public/providers/openclaw.png" alt="OpenClaw" width="48"/><br/>
|
||||
<b>OpenClaw</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 205K</sub>
|
||||
</td>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/HKUDS/nanobot">
|
||||
<img src="./public/providers/nanobot.png" alt="NanoBot" width="48"/><br/>
|
||||
<b>NanoBot</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 20.9K</sub>
|
||||
</td>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/sipeed/picoclaw">
|
||||
<img src="./public/providers/picoclaw.jpg" alt="PicoClaw" width="48"/><br/>
|
||||
<b>PicoClaw</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 14.6K</sub>
|
||||
</td>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/zeroclaw-labs/zeroclaw">
|
||||
<img src="./public/providers/zeroclaw.png" alt="ZeroClaw" width="48"/><br/>
|
||||
<b>ZeroClaw</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 9.9K</sub>
|
||||
</td>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/nearai/ironclaw">
|
||||
<img src="./public/providers/ironclaw.png" alt="IronClaw" width="48"/><br/>
|
||||
<b>IronClaw</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 2.1K</sub>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/anomalyco/opencode">
|
||||
<img src="./public/providers/opencode.svg" alt="OpenCode" width="48"/><br/>
|
||||
<b>OpenCode</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 106K</sub>
|
||||
</td>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/openai/codex">
|
||||
<img src="./public/providers/codex.png" alt="Codex CLI" width="48"/><br/>
|
||||
<b>Codex CLI</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 60.8K</sub>
|
||||
</td>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/anthropics/claude-code">
|
||||
<img src="./public/providers/claude.png" alt="Claude Code" width="48"/><br/>
|
||||
<b>Claude Code</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 67.3K</sub>
|
||||
</td>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/google-gemini/gemini-cli">
|
||||
<img src="./public/providers/gemini-cli.png" alt="Gemini CLI" width="48"/><br/>
|
||||
<b>Gemini CLI</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 94.7K</sub>
|
||||
</td>
|
||||
<td align="center" width="110">
|
||||
<a href="https://github.com/Kilo-Org/kilocode">
|
||||
<img src="./public/providers/kilocode.png" alt="Kilo Code" width="48"/><br/>
|
||||
<b>Kilo Code</b>
|
||||
</a><br/>
|
||||
<sub>⭐ 15.5K</sub>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<sub>📡 所有代理通过 <code>http://localhost:20128/v1</code> 或 <code>http://cloud.omniroute.online/v1</code> 连接 — 一个配置，无限模型和配额</sub>
|
||||
|
||||
---
|
||||
|
||||
[](https://www.npmjs.com/package/omniroute)
|
||||
[](https://hub.docker.com/r/diegosouzapw/omniroute)
|
||||
[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
|
||||
[](https://omniroute.online)
|
||||
|
||||
[🌐 网站](https://omniroute.online) • [🚀 快速开始](#-快速开始) • [💡 功能特性](#-核心功能) • [📖 文档](#-文档) • [💰 定价](#-定价概览)
|
||||
|
||||
🌐 **多语言版本：** [English](README.md) | [Português](README.pt-BR.md) | [Español](README.es.md) | [Русский](README.ru.md) | [中文](README.zh-CN.md) | [Deutsch](README.de.md) | [Français](README.fr.md) | [Italiano](README.it.md)
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## 🤔 为什么选择 OmniRoute？
|
||||
|
||||
**停止浪费金钱和遭遇限制：**
|
||||
|
||||
- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> 订阅配额每月未使用就过期
|
||||
- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> 速率限制在编程中途停止你
|
||||
- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> 昂贵的 API（每个提供商 $20-50/月）
|
||||
- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> 手动在提供商间切换
|
||||
|
||||
**OmniRoute 解决这些问题：**
|
||||
|
||||
- ✅ **最大化订阅** — 追踪配额，在重置前用完每一点
|
||||
- ✅ **自动故障转移** — 订阅 → API Key → 低价 → 免费，零停机
|
||||
- ✅ **多账号** — 每个提供商的账号轮询
|
||||
- ✅ **通用** — 适用于 Claude Code、Codex、Gemini CLI、Cursor、Cline、OpenClaw、任何 CLI 工具
|
||||
|
||||
---
|
||||
|
||||
## 🔄 工作原理
|
||||
|
||||
```
|
||||
┌─────────────┐
|
||||
│ 您的 CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)
|
||||
│ 工具 │
|
||||
└──────┬──────┘
|
||||
│ http://localhost:20128/v1
|
||||
↓
|
||||
┌─────────────────────────────────────────┐
|
||||
│ OmniRoute（智能路由器） │
|
||||
│ • 格式转换（OpenAI ↔ Claude） │
|
||||
│ • 配额追踪 + Embeddings + 图像 │
|
||||
│ • 自动令牌刷新 │
|
||||
└──────┬──────────────────────────────────┘
|
||||
│
|
||||
├─→ [第1层: 订阅] Claude Code, Codex, Gemini CLI
|
||||
│ ↓ 配额用完
|
||||
├─→ [第2层: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM 等
|
||||
│ ↓ 预算限制
|
||||
├─→ [第3层: 低价] GLM ($0.6/1M), MiniMax ($0.2/1M)
|
||||
│ ↓ 预算限制
|
||||
└─→ [第4层: 免费] iFlow, Qwen, Kiro（无限制）
|
||||
|
||||
结果：永不停止编程，成本最低
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚡ 快速开始
|
||||
|
||||
**1. 全局安装：**
|
||||
|
||||
```bash
|
||||
npm install -g omniroute
|
||||
omniroute
|
||||
```
|
||||
|
||||
🎉 仪表板在 `http://localhost:20128` 打开
|
||||
|
||||
| 命令 | 描述 |
|
||||
| ----------------------- | ---------------------------- |
|
||||
| `omniroute` | 启动服务器（默认端口 20128） |
|
||||
| `omniroute --port 3000` | 使用自定义端口 |
|
||||
| `omniroute --no-open` | 不自动打开浏览器 |
|
||||
| `omniroute --help` | 显示帮助 |
|
||||
|
||||
**2. 连接免费提供商：**
|
||||
|
||||
仪表板 → 提供商 → 连接 **Claude Code** 或 **Antigravity** → OAuth 登录 → 完成！
|
||||
|
||||
**3. 在 CLI 工具中使用：**
|
||||
|
||||
```
|
||||
Claude Code/Codex/Gemini CLI/OpenClaw/Cursor/Cline 设置：
|
||||
Endpoint: http://localhost:20128/v1
|
||||
API Key: [从仪表板复制]
|
||||
Model: if/kimi-k2-thinking
|
||||
```
|
||||
|
||||
**完成！** 开始使用免费 AI 模型编程。
|
||||
|
||||
**替代方案 — 从源代码运行：**
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
npm install
|
||||
PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🐳 Docker
|
||||
|
||||
OmniRoute 作为公共 Docker 镜像在 [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute) 上可用。
|
||||
|
||||
**快速运行：**
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
--name omniroute \
|
||||
--restart unless-stopped \
|
||||
-p 20128:20128 \
|
||||
-v omniroute-data:/app/data \
|
||||
diegosouzapw/omniroute:latest
|
||||
```
|
||||
|
||||
**使用环境文件：**
|
||||
|
||||
```bash
|
||||
# 先复制并编辑 .env
|
||||
cp .env.example .env
|
||||
|
||||
docker run -d \
|
||||
--name omniroute \
|
||||
--restart unless-stopped \
|
||||
--env-file .env \
|
||||
-p 20128:20128 \
|
||||
-v omniroute-data:/app/data \
|
||||
diegosouzapw/omniroute:latest
|
||||
```
|
||||
|
||||
**使用 Docker Compose：**
|
||||
|
||||
```bash
|
||||
# 基础配置（无 CLI 工具）
|
||||
docker compose --profile base up -d
|
||||
|
||||
# CLI 配置（内置 Claude Code、Codex、OpenClaw）
|
||||
docker compose --profile cli up -d
|
||||
```
|
||||
|
||||
| 镜像 | 标签 | 大小 | 描述 |
|
||||
| ------------------------ | -------- | ------ | ---------- |
|
||||
| `diegosouzapw/omniroute` | `latest` | ~250MB | 最新稳定版 |
|
||||
| `diegosouzapw/omniroute` | `0.9.0` | ~250MB | 当前版本 |
|
||||
|
||||
---
|
||||
|
||||
## 💰 定价概览
|
||||
|
||||
| 层级 | 提供商 | 费用 | 配额重置 | 最适合 |
|
||||
| -------------- | ----------------- | --------------------- | --------------- | ------------ |
|
||||
| **💳 订阅** | Claude Code (Pro) | $20/月 | 5小时 + 每周 | 已订阅用户 |
|
||||
| | Codex (Plus/Pro) | $20-200/月 | 5小时 + 每周 | OpenAI 用户 |
|
||||
| | Gemini CLI | **免费** | 180K/月 + 1K/天 | 所有人！ |
|
||||
| | GitHub Copilot | $10-19/月 | 每月 | GitHub 用户 |
|
||||
| **🔑 API KEY** | NVIDIA NIM | **免费**（1000 积分） | 一次性 | 免费测试 |
|
||||
| | DeepSeek | 按使用量 | 无 | 最佳性价比 |
|
||||
| | Groq | 免费层 + 付费 | 限速 | 超快推理 |
|
||||
| | xAI (Grok) | 按使用量 | 无 | Grok 模型 |
|
||||
| | Mistral | 免费层 + 付费 | 限速 | 欧洲 AI |
|
||||
| | OpenRouter | 按使用量 | 无 | 100+ 模型 |
|
||||
| **💰 低价** | GLM-4.7 | $0.6/1M | 每日 10时 | 经济备用 |
|
||||
| | MiniMax M2.1 | $0.2/1M | 5小时滚动 | 最便宜选项 |
|
||||
| | Kimi K2 | $9/月固定 | 每月 10M Token | 可预测成本 |
|
||||
| **🆓 免费** | iFlow | $0 | 无限制 | 8 个免费模型 |
|
||||
| | Qwen | $0 | 无限制 | 3 个免费模型 |
|
||||
| | Kiro | $0 | 无限制 | 免费 Claude |
|
||||
|
||||
**💡 专业建议：** 从 Gemini CLI（每月 180K 免费）+ iFlow（无限免费）开始 = $0 成本！
|
||||
|
||||
---
|
||||
|
||||
## 🎯 使用场景
|
||||
|
||||
### 场景 1："我有 Claude Pro 订阅"
|
||||
|
||||
**问题：** 配额未使用就过期，编程高峰期遇到速率限制
|
||||
|
||||
```
|
||||
Combo: "maximize-claude"
|
||||
1. cc/claude-opus-4-6 （充分使用订阅）
|
||||
2. glm/glm-4.7 （配额用完时的便宜备用）
|
||||
3. if/kimi-k2-thinking （免费应急后备）
|
||||
|
||||
每月成本：$20（订阅）+ ~$5（备用）= $25 总计
|
||||
对比：$20 + 遇到限制 = 受挫
|
||||
```
|
||||
|
||||
### 场景 2："我想要零成本"
|
||||
|
||||
**问题：** 无法承担订阅费用，需要可靠的 AI 编程
|
||||
|
||||
```
|
||||
Combo: "free-forever"
|
||||
1. gc/gemini-3-flash （每月 180K 免费）
|
||||
2. if/kimi-k2-thinking （无限免费）
|
||||
3. qw/qwen3-coder-plus （无限免费）
|
||||
|
||||
每月成本：$0
|
||||
质量：生产级模型
|
||||
```
|
||||
|
||||
### 场景 3："我需要 24/7 编程，不中断"
|
||||
|
||||
**问题：** 截止日期紧迫，不能有停机时间
|
||||
|
||||
```
|
||||
Combo: "always-on"
|
||||
1. cc/claude-opus-4-6 （最佳质量）
|
||||
2. cx/gpt-5.2-codex （第二个订阅）
|
||||
3. glm/glm-4.7 （便宜，每日重置）
|
||||
4. minimax/MiniMax-M2.1 （最便宜，5小时重置）
|
||||
5. if/kimi-k2-thinking （免费无限制）
|
||||
|
||||
结果：5 层故障转移 = 零停机
|
||||
```
|
||||
|
||||
### 场景 4："我想在 OpenClaw 中使用免费 AI"
|
||||
|
||||
**问题：** 需要在消息应用中使用 AI 助手，完全免费
|
||||
|
||||
```
|
||||
Combo: "openclaw-free"
|
||||
1. if/glm-4.7 （无限免费）
|
||||
2. if/minimax-m2.1 （无限免费）
|
||||
3. if/kimi-k2-thinking （无限免费）
|
||||
|
||||
每月成本：$0
|
||||
访问方式：WhatsApp、Telegram、Slack、Discord、iMessage、Signal...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 💡 核心功能
|
||||
|
||||
### 🧠 路由与智能
|
||||
|
||||
| 功能 | 功能描述 |
|
||||
| ------------------------- | -------------------------------------------------------------------------- |
|
||||
| 🎯 **智能 4 层故障转移** | 自动路由：订阅 → API Key → 低价 → 免费 |
|
||||
| 📊 **实时配额追踪** | 实时 Token 计数 + 每个提供商的重置倒计时 |
|
||||
| 🔄 **格式转换** | OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro 无缝切换 |
|
||||
| 👥 **多账号支持** | 每个提供商多个账号，智能选择 |
|
||||
| 🔄 **自动令牌刷新** | OAuth 令牌自动刷新并重试 |
|
||||
| 🎨 **自定义组合** | 6 种策略：fill-first、round-robin、p2c、random、least-used、cost-optimized |
|
||||
| 🧩 **自定义模型** | 为任何提供商添加任何模型 ID |
|
||||
| 🌐 **通配符路由** | 动态路由 `provider/*` 模式到任何提供商 |
|
||||
| 🧠 **推理预算** | passthrough、auto、custom 和 adaptive 模式用于推理模型 |
|
||||
| 💬 **System Prompt 注入** | 全局 System Prompt 应用于所有请求 |
|
||||
| 📄 **Responses API** | 完整支持 OpenAI Responses API (`/v1/responses`) 用于 Codex |
|
||||
|
||||
### 🎵 多模态 API
|
||||
|
||||
| 功能 | 功能描述 |
|
||||
| ----------------- | ---------------------------------------------- |
|
||||
| 🖼️ **图像生成** | `/v1/images/generations` — 4 个提供商，9+ 模型 |
|
||||
| 📐 **Embeddings** | `/v1/embeddings` — 6 个提供商，9+ 模型 |
|
||||
| 🎤 **音频转录** | `/v1/audio/transcriptions` — Whisper 兼容 |
|
||||
| 🔊 **文字转语音** | `/v1/audio/speech` — 多提供商音频合成 |
|
||||
| 🛡️ **内容审核** | `/v1/moderations` — 内容安全检查 |
|
||||
| 🔀 **重排序** | `/v1/rerank` — 文档相关性重排序 |
|
||||
|
||||
### 🛡️ 弹性与安全
|
||||
|
||||
| 功能 | 功能描述 |
|
||||
| --------------------- | -------------------------------------- |
|
||||
| 🔌 **断路器** | 每个提供商自动打开/关闭，可配置阈值 |
|
||||
| 🛡️ **反惊群** | Mutex + 信号量限速用于 API Key 提供商 |
|
||||
| 🧠 **语义缓存** | 两层缓存（签名 + 语义）降低成本和延迟 |
|
||||
| ⚡ **请求幂等性** | 5 秒去重窗口防止重复请求 |
|
||||
| 🔒 **TLS 指纹伪装** | 通过 wreq-js 绕过基于 TLS 的机器人检测 |
|
||||
| 🌐 **IP 过滤** | 白名单/黑名单用于 API 访问控制 |
|
||||
| 📊 **可编辑速率限制** | 可配置的 RPM、最小间隔和最大并发 |
|
||||
|
||||
### 📊 可观察性与分析
|
||||
|
||||
| 功能 | 功能描述 |
|
||||
| ------------------ | ------------------------------------------ |
|
||||
| 📝 **请求日志** | 调试模式，完整的请求/响应日志 |
|
||||
| 💾 **SQLite 日志** | 持久化代理日志，服务器重启后仍然保留 |
|
||||
| 📊 **分析仪表板** | Recharts：统计卡片、使用量图表、提供商表格 |
|
||||
| 📈 **进度追踪** | 流式传输的 SSE 进度事件（可选） |
|
||||
| 🧪 **LLM 评估** | 黄金集测试，4 种匹配策略 |
|
||||
| 🔍 **请求遥测** | p50/p95/p99 延迟聚合 + X-Request-Id 追踪 |
|
||||
| 📋 **日志 + 配额** | 专用页面用于日志浏览和配额追踪 |
|
||||
| 🏥 **健康仪表板** | 运行时间、断路器状态、锁定、缓存统计 |
|
||||
| 💰 **成本追踪** | 预算管理 + 每模型定价配置 |
|
||||
|
||||
### ☁️ 部署与同步
|
||||
|
||||
| 功能 | 功能描述 |
|
||||
| --------------------- | ---------------------------------------------------------- |
|
||||
| 💾 **Cloud Sync** | 通过 Cloudflare Workers 在设备间同步配置 |
|
||||
| 🌐 **随处部署** | Localhost、VPS、Docker、Cloudflare Workers |
|
||||
| 🔑 **API Key 管理** | 按提供商生成、轮换和设定 API Key 范围 |
|
||||
| 🧙 **配置向导** | 4 步引导式设置，面向新用户 |
|
||||
| 🔧 **CLI 工具仪表板** | 一键配置 Claude、Codex、Cline、OpenClaw、Kilo、Antigravity |
|
||||
| 🔄 **数据库备份** | 自动备份和恢复所有设置 |
|
||||
|
||||
<details>
|
||||
<summary><b>📖 功能详情</b></summary>
|
||||
|
||||
### 🎯 智能 4 层故障转移
|
||||
|
||||
创建带自动故障转移的组合：
|
||||
|
||||
```
|
||||
Combo: "my-coding-stack"
|
||||
1. cc/claude-opus-4-6 （您的订阅）
|
||||
2. nvidia/llama-3.3-70b （免费 NVIDIA API）
|
||||
3. glm/glm-4.7 （便宜备用，$0.6/1M）
|
||||
4. if/kimi-k2-thinking （免费后备）
|
||||
|
||||
→ 配额用完或出错时自动切换
|
||||
```
|
||||
|
||||
### 📊 实时配额追踪
|
||||
|
||||
- 每个提供商的 Token 消耗
|
||||
- 重置倒计时（5 小时、每日、每周）
|
||||
- 付费层级的成本估算
|
||||
- 月度支出报告
|
||||
|
||||
### 🔄 格式转换
|
||||
|
||||
格式间的无缝转换：
|
||||
|
||||
- **OpenAI** ↔ **Claude** ↔ **Gemini** ↔ **OpenAI Responses**
|
||||
- 您的 CLI 发送 OpenAI 格式 → OmniRoute 转换 → 提供商接收原生格式
|
||||
- 适用于任何支持自定义 OpenAI 端点的工具
|
||||
|
||||
### 👥 多账号支持
|
||||
|
||||
- 每个提供商添加多个账号
|
||||
- 自动轮询或基于优先级的路由
|
||||
- 当一个账号达到配额时自动切换到下一个
|
||||
|
||||
### 🔄 自动令牌刷新
|
||||
|
||||
- OAuth 令牌在过期前自动刷新
|
||||
- 无需手动重新认证
|
||||
- 所有提供商的无缝体验
|
||||
|
||||
### 🎨 自定义组合
|
||||
|
||||
- 创建无限模型组合
|
||||
- 6 种策略：fill-first、round-robin、power-of-two-choices、random、least-used、cost-optimized
|
||||
- 通过 Cloud Sync 在设备间共享组合
|
||||
|
||||
### 🏥 健康仪表板
|
||||
|
||||
- 系统状态（运行时间、版本、内存使用）
|
||||
- 每个提供商的断路器状态（Closed/Open/Half-Open）
|
||||
- 速率限制状态和活动锁定
|
||||
- 签名缓存统计
|
||||
- 延迟遥测（p50/p95/p99）+ 提示缓存
|
||||
- 一键重置健康状态
|
||||
|
||||
### 🔧 翻译器 Playground
|
||||
|
||||
- 调试、测试和可视化 API 格式转换
|
||||
- 发送请求并查看 OmniRoute 如何在提供商格式间转换
|
||||
- 对排查集成问题非常有价值
|
||||
|
||||
### 💾 Cloud Sync
|
||||
|
||||
- 在设备间同步提供商、组合和设置
|
||||
- 自动后台同步
|
||||
- 安全加密存储
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## 📖 设置指南
|
||||
|
||||
<details>
|
||||
<summary><b>💳 订阅提供商</b></summary>
|
||||
|
||||
### Claude Code (Pro/Max)
|
||||
|
||||
```bash
|
||||
仪表板 → 提供商 → 连接 Claude Code
|
||||
→ OAuth 登录 → 自动令牌刷新
|
||||
→ 5 小时 + 每周配额追踪
|
||||
|
||||
模型：
|
||||
cc/claude-opus-4-6
|
||||
cc/claude-sonnet-4-5-20250929
|
||||
cc/claude-haiku-4-5-20251001
|
||||
```
|
||||
|
||||
**专业建议：** 复杂任务用 Opus，追求速度用 Sonnet。OmniRoute 按模型追踪配额！
|
||||
|
||||
### OpenAI Codex (Plus/Pro)
|
||||
|
||||
```bash
|
||||
仪表板 → 提供商 → 连接 Codex
|
||||
→ OAuth 登录（端口 1455）
|
||||
→ 5 小时 + 每周重置
|
||||
|
||||
模型：
|
||||
cx/gpt-5.2-codex
|
||||
cx/gpt-5.1-codex-max
|
||||
```
|
||||
|
||||
### Gemini CLI（免费 180K/月！）
|
||||
|
||||
```bash
|
||||
仪表板 → 提供商 → 连接 Gemini CLI
|
||||
→ Google OAuth
|
||||
→ 每月 180K completions + 每天 1K
|
||||
|
||||
模型：
|
||||
gc/gemini-3-flash-preview
|
||||
gc/gemini-2.5-pro
|
||||
```
|
||||
|
||||
**最佳价值：** 巨大的免费额度！在付费层级之前使用。
|
||||
|
||||
### GitHub Copilot
|
||||
|
||||
```bash
|
||||
仪表板 → 提供商 → 连接 GitHub
|
||||
→ 通过 GitHub OAuth
|
||||
→ 每月重置（每月 1 日）
|
||||
|
||||
模型：
|
||||
gh/gpt-5
|
||||
gh/claude-4.5-sonnet
|
||||
gh/gemini-3-pro
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>🔑 API Key 提供商</b></summary>
|
||||
|
||||
### NVIDIA NIM（免费 1000 积分！）
|
||||
|
||||
1. 注册：[build.nvidia.com](https://build.nvidia.com)
|
||||
2. 获取免费 API key（包含 1000 推理积分）
|
||||
3. 仪表板 → 添加提供商 → NVIDIA NIM：
|
||||
- API Key：`nvapi-your-key`
|
||||
|
||||
**模型：** `nvidia/llama-3.3-70b-instruct`、`nvidia/mistral-7b-instruct` 及 50+ 更多
|
||||
|
||||
**专业建议：** OpenAI 兼容的 API — 与 OmniRoute 的格式转换完美配合！
|
||||
|
||||
### DeepSeek
|
||||
|
||||
1. 注册：[platform.deepseek.com](https://platform.deepseek.com)
|
||||
2. 获取 API key
|
||||
3. 仪表板 → 添加提供商 → DeepSeek
|
||||
|
||||
**模型：** `deepseek/deepseek-chat`、`deepseek/deepseek-coder`
|
||||
|
||||
### Groq（免费层可用！）
|
||||
|
||||
1. 注册：[console.groq.com](https://console.groq.com)
|
||||
2. 获取 API key（包含免费层）
|
||||
3. 仪表板 → 添加提供商 → Groq
|
||||
|
||||
**模型：** `groq/llama-3.3-70b`、`groq/mixtral-8x7b`
|
||||
|
||||
**专业建议：** 超快推理 — 最适合实时编程！
|
||||
|
||||
### OpenRouter（100+ 模型）
|
||||
|
||||
1. 注册：[openrouter.ai](https://openrouter.ai)
|
||||
2. 获取 API key
|
||||
3. 仪表板 → 添加提供商 → OpenRouter
|
||||
|
||||
**模型：** 通过一个 API key 访问所有主要提供商的 100+ 模型。
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>💰 低价提供商（备用）</b></summary>
|
||||
|
||||
### GLM-4.7（每日重置，$0.6/1M）
|
||||
|
||||
1. 注册：[Zhipu AI](https://open.bigmodel.cn/)
|
||||
2. 从 Coding Plan 获取 API key
|
||||
3. 仪表板 → 添加 API Key：
|
||||
- 提供商：`glm`
|
||||
- API Key：`your-key`
|
||||
|
||||
**使用：** `glm/glm-4.7`
|
||||
|
||||
**专业建议：** Coding Plan 以 1/7 的价格提供 3 倍配额！每日 10:00 AM 重置。
|
||||
|
||||
### MiniMax M2.1（5 小时重置，$0.20/1M）
|
||||
|
||||
1. 注册：[MiniMax](https://www.minimax.io/)
|
||||
2. 获取 API key
|
||||
3. 仪表板 → 添加 API Key
|
||||
|
||||
**使用：** `minimax/MiniMax-M2.1`
|
||||
|
||||
**专业建议：** 长上下文（1M Token）最便宜的选项！
|
||||
|
||||
### Kimi K2（$9/月固定）
|
||||
|
||||
1. 订阅：[Moonshot AI](https://platform.moonshot.ai/)
|
||||
2. 获取 API key
|
||||
3. 仪表板 → 添加 API Key
|
||||
|
||||
**使用：** `kimi/kimi-latest`
|
||||
|
||||
**专业建议：** 固定 $9/月 10M Token = $0.90/1M 有效成本！
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>🆓 免费提供商（应急备用）</b></summary>
|
||||
|
||||
### iFlow（8 个免费模型）
|
||||
|
||||
```bash
|
||||
仪表板 → 连接 iFlow
|
||||
→ iFlow OAuth 登录
|
||||
→ 无限使用
|
||||
|
||||
模型：
|
||||
if/kimi-k2-thinking
|
||||
if/qwen3-coder-plus
|
||||
if/glm-4.7
|
||||
if/minimax-m2
|
||||
if/deepseek-r1
|
||||
```
|
||||
|
||||
### Qwen（3 个免费模型）
|
||||
|
||||
```bash
|
||||
仪表板 → 连接 Qwen
|
||||
→ 设备码授权
|
||||
→ 无限使用
|
||||
|
||||
模型：
|
||||
qw/qwen3-coder-plus
|
||||
qw/qwen3-coder-flash
|
||||
```
|
||||
|
||||
### Kiro（免费 Claude）
|
||||
|
||||
```bash
|
||||
仪表板 → 连接 Kiro
|
||||
→ AWS Builder ID 或 Google/GitHub
|
||||
→ 无限使用
|
||||
|
||||
模型：
|
||||
kr/claude-sonnet-4.5
|
||||
kr/claude-haiku-4.5
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>🎨 创建组合</b></summary>
|
||||
|
||||
### 示例 1：最大化订阅 → 便宜备用
|
||||
|
||||
```
|
||||
仪表板 → 组合 → 创建新的
|
||||
|
||||
名称：premium-coding
|
||||
模型：
|
||||
1. cc/claude-opus-4-6（订阅主力）
|
||||
2. glm/glm-4.7（便宜备用，$0.6/1M）
|
||||
3. minimax/MiniMax-M2.1（最便宜的后备，$0.20/1M）
|
||||
|
||||
在 CLI 中使用：premium-coding
|
||||
```
|
||||
|
||||
### 示例 2：仅免费（零成本）
|
||||
|
||||
```
|
||||
名称：free-combo
|
||||
模型：
|
||||
1. gc/gemini-3-flash-preview（每月 180K 免费）
|
||||
2. if/kimi-k2-thinking（无限制）
|
||||
3. qw/qwen3-coder-plus（无限制）
|
||||
|
||||
成本：永远 $0！
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>🔧 CLI 集成</b></summary>
|
||||
|
||||
### Cursor IDE
|
||||
|
||||
```
|
||||
设置 → 模型 → 高级：
|
||||
OpenAI API Base URL: http://localhost:20128/v1
|
||||
OpenAI API Key: [从 OmniRoute 仪表板获取]
|
||||
Model: cc/claude-opus-4-6
|
||||
```
|
||||
|
||||
### Claude Code
|
||||
|
||||
使用仪表板中的 **CLI Tools** 页面一键配置，或手动编辑 `~/.claude/settings.json`。
|
||||
|
||||
### Codex CLI
|
||||
|
||||
```bash
|
||||
export OPENAI_BASE_URL="http://localhost:20128"
|
||||
export OPENAI_API_KEY="your-omniroute-api-key"
|
||||
|
||||
codex "your prompt"
|
||||
```
|
||||
|
||||
### OpenClaw
|
||||
|
||||
**选项 1 — 仪表板（推荐）：**
|
||||
|
||||
```
|
||||
仪表板 → CLI Tools → OpenClaw → 选择模型 → 应用
|
||||
```
|
||||
|
||||
**选项 2 — 手动：** 编辑 `~/.openclaw/openclaw.json`：
|
||||
|
||||
```json
|
||||
{
|
||||
"models": {
|
||||
"providers": {
|
||||
"omniroute": {
|
||||
"baseUrl": "http://127.0.0.1:20128/v1",
|
||||
"apiKey": "sk_omniroute",
|
||||
"api": "openai-completions"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> **注意：** OpenClaw 仅支持本地 OmniRoute。使用 `127.0.0.1` 而非 `localhost` 以避免 IPv6 解析问题。
|
||||
|
||||
### Cline / Continue / RooCode
|
||||
|
||||
```
|
||||
设置 → API 配置：
|
||||
提供商：OpenAI Compatible
|
||||
Base URL: http://localhost:20128/v1
|
||||
API Key: [从 OmniRoute 仪表板获取]
|
||||
Model: if/kimi-k2-thinking
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## 📊 可用模型
|
||||
|
||||
<details>
|
||||
<summary><b>查看所有可用模型</b></summary>
|
||||
|
||||
**Claude Code (`cc/`)** - Pro/Max:
|
||||
|
||||
- `cc/claude-opus-4-6`
|
||||
- `cc/claude-sonnet-4-5-20250929`
|
||||
- `cc/claude-haiku-4-5-20251001`
|
||||
|
||||
**Codex (`cx/`)** - Plus/Pro:
|
||||
|
||||
- `cx/gpt-5.2-codex`
|
||||
- `cx/gpt-5.1-codex-max`
|
||||
|
||||
**Gemini CLI (`gc/`)** - 免费:
|
||||
|
||||
- `gc/gemini-3-flash-preview`
|
||||
- `gc/gemini-2.5-pro`
|
||||
|
||||
**GitHub Copilot (`gh/`)**:
|
||||
|
||||
- `gh/gpt-5`
|
||||
- `gh/claude-4.5-sonnet`
|
||||
|
||||
**NVIDIA NIM (`nvidia/`)** - 免费积分:
|
||||
|
||||
- `nvidia/llama-3.3-70b-instruct`
|
||||
- `nvidia/mistral-7b-instruct`
|
||||
- 50+ 更多模型在 [build.nvidia.com](https://build.nvidia.com)
|
||||
|
||||
**GLM (`glm/`)** - $0.6/1M:
|
||||
|
||||
- `glm/glm-4.7`
|
||||
|
||||
**MiniMax (`minimax/`)** - $0.2/1M:
|
||||
|
||||
- `minimax/MiniMax-M2.1`
|
||||
|
||||
**iFlow (`if/`)** - 免费:
|
||||
|
||||
- `if/kimi-k2-thinking`
|
||||
- `if/qwen3-coder-plus`
|
||||
- `if/deepseek-r1`
|
||||
- `if/glm-4.7`
|
||||
- `if/minimax-m2`
|
||||
|
||||
**Qwen (`qw/`)** - 免费:
|
||||
|
||||
- `qw/qwen3-coder-plus`
|
||||
- `qw/qwen3-coder-flash`
|
||||
|
||||
**Kiro (`kr/`)** - 免费:
|
||||
|
||||
- `kr/claude-sonnet-4.5`
|
||||
- `kr/claude-haiku-4.5`
|
||||
|
||||
**OpenRouter (`or/`)** - 100+ 模型:
|
||||
|
||||
- `or/anthropic/claude-4-sonnet`
|
||||
- `or/google/gemini-2.5-pro`
|
||||
- [openrouter.ai/models](https://openrouter.ai/models) 上的任何模型
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## 🧪 评估 (Evals)
|
||||
|
||||
OmniRoute 包含内置评估框架，用于针对黄金集测试 LLM 响应质量。通过仪表板中的 **Analytics → Evals** 访问。
|
||||
|
||||
### 内置黄金集
|
||||
|
||||
预加载的「OmniRoute Golden Set」包含 10 个测试用例：
|
||||
|
||||
- 问候、数学、地理、代码生成
|
||||
- JSON 格式合规性、翻译、markdown
|
||||
- 安全拒绝（有害内容）、计数、布尔逻辑
|
||||
|
||||
### 评估策略
|
||||
|
||||
| 策略 | 描述 | 示例 |
|
||||
| ---------- | -------------------------------- | -------------------------------- |
|
||||
| `exact` | 输出必须完全匹配 | `"4"` |
|
||||
| `contains` | 输出必须包含子串（不区分大小写） | `"Paris"` |
|
||||
| `regex` | 输出必须匹配正则表达式模式 | `"1.*2.*3"` |
|
||||
| `custom` | 自定义 JS 函数返回 true/false | `(output) => output.length > 10` |
|
||||
|
||||
---
|
||||
|
||||
## 🐛 故障排除
|
||||
|
||||
<details>
|
||||
<summary><b>点击展开故障排除指南</b></summary>
|
||||
|
||||
**"Language model did not provide messages"**
|
||||
|
||||
- 提供商配额已耗尽 → 检查仪表板配额追踪器
|
||||
- 解决方案：使用组合故障转移或切换到更便宜的层级
|
||||
|
||||
**速率限制**
|
||||
|
||||
- 订阅配额耗尽 → 回退到 GLM/MiniMax
|
||||
- 添加组合：`cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
|
||||
|
||||
**OAuth 令牌过期**
|
||||
|
||||
- OmniRoute 自动刷新
|
||||
- 如果问题持续：仪表板 → 提供商 → 重新连接
|
||||
|
||||
**高成本**
|
||||
|
||||
- 在仪表板 → 成本中检查使用统计
|
||||
- 将主要模型切换为 GLM/MiniMax
|
||||
- 对非关键任务使用免费层（Gemini CLI、iFlow）
|
||||
|
||||
**仪表板在错误端口打开**
|
||||
|
||||
- 设置 `PORT=20128` 和 `NEXT_PUBLIC_BASE_URL=http://localhost:20128`
|
||||
|
||||
**Cloud sync 错误**
|
||||
|
||||
- 验证 `BASE_URL` 指向您正在运行的实例
|
||||
- 验证 `CLOUD_URL` 指向预期的云端点
|
||||
- 保持 `NEXT_PUBLIC_*` 值与服务器端值一致
|
||||
|
||||
**首次登录不工作**
|
||||
|
||||
- 检查 `.env` 中的 `INITIAL_PASSWORD`
|
||||
- 如未设置，默认密码为 `123456`
|
||||
|
||||
**没有请求日志**
|
||||
|
||||
- 在 `.env` 中设置 `ENABLE_REQUEST_LOGS=true`
|
||||
|
||||
**兼容 OpenAI 的提供商连接测试显示 "Invalid"**
|
||||
|
||||
- 许多提供商不暴露 `/models` 端点
|
||||
- OmniRoute v0.9.0+ 包含通过 chat completions 的回退验证
|
||||
- 确保 base URL 包含 `/v1` 后缀
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ 技术栈
|
||||
|
||||
- **运行时**: Node.js 20+
|
||||
- **语言**: TypeScript 5.9 — `src/` 和 `open-sse/` 中 **100% TypeScript**（v0.9.0）
|
||||
- **框架**: Next.js 16 + React 19 + Tailwind CSS 4
|
||||
- **数据库**: LowDB (JSON) + SQLite（领域状态 + 代理日志）
|
||||
- **流式传输**: Server-Sent Events (SSE)
|
||||
- **认证**: OAuth 2.0 (PKCE) + JWT + API Keys
|
||||
- **测试**: Node.js test runner（368+ 单元测试）
|
||||
- **CI/CD**: GitHub Actions（发布时自动 npm 发布 + Docker Hub）
|
||||
- **网站**: [omniroute.online](https://omniroute.online)
|
||||
- **包**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)
|
||||
- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)
|
||||
- **弹性**: 断路器、指数退避、反惊群、TLS 伪装
|
||||
|
||||
---
|
||||
|
||||
## 📖 文档
|
||||
|
||||
| 文档 | 描述 |
|
||||
| ----------------------------------- | ---------------------------- |
|
||||
| [用户指南](docs/USER_GUIDE.md) | 提供商、组合、CLI 集成、部署 |
|
||||
| [API 参考](docs/API_REFERENCE.md) | 所有端点及示例 |
|
||||
| [故障排除](docs/TROUBLESHOOTING.md) | 常见问题和解决方案 |
|
||||
| [架构](docs/ARCHITECTURE.md) | 系统架构和内部机制 |
|
||||
| [贡献指南](CONTRIBUTING.md) | 开发设置和指南 |
|
||||
| [OpenAPI 规范](docs/openapi.yaml) | OpenAPI 3.0 规范 |
|
||||
| [安全策略](SECURITY.md) | 漏洞报告和安全实践 |
|
||||
|
||||
---
|
||||
|
||||
## 📧 支持
|
||||
|
||||
- **网站**: [omniroute.online](https://omniroute.online)
|
||||
- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
|
||||
- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
|
||||
- **原始项目**: [decolua 的 9router](https://github.com/decolua/9router)
|
||||
|
||||
---
|
||||
|
||||
## 👥 贡献者
|
||||
|
||||
[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
|
||||
|
||||
### 如何贡献
|
||||
|
||||
1. Fork 仓库
|
||||
2. 创建功能分支（`git checkout -b feature/amazing-feature`）
|
||||
3. 提交更改（`git commit -m 'Add amazing feature'`）
|
||||
4. 推送到分支（`git push origin feature/amazing-feature`）
|
||||
5. 打开 Pull Request
|
||||
|
||||
详细指南请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
|
||||
|
||||
### 发布新版本
|
||||
|
||||
```bash
|
||||
# 创建发布 — npm 发布自动完成
|
||||
gh release create v0.9.0 --title "v0.9.0" --generate-notes
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Star 历史
|
||||
|
||||
<a href="https://star-history.com/#diegosouzapw/OmniRoute&Date">
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=diegosouzapw/OmniRoute&type=Date&theme=dark" />
|
||||
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=diegosouzapw/OmniRoute&type=Date" />
|
||||
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=diegosouzapw/OmniRoute&type=Date" />
|
||||
</picture>
|
||||
</a>
|
||||
|
||||
---
|
||||
|
||||
## 🙏 致谢
|
||||
|
||||
特别感谢 **[decolua](https://github.com/decolua)** 的 **[9router](https://github.com/decolua/9router)** — 启发了本 fork 的原始项目。OmniRoute 在这个令人难以置信的基础上添加了额外功能、多模态 API 和完整的 TypeScript 重写。
|
||||
|
||||
特别感谢 **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — 启发了本 JavaScript 移植的原始 Go 实现。
|
||||
|
||||
---
|
||||
|
||||
## 📄 许可证
|
||||
|
||||
MIT 许可证 — 详见 [LICENSE](LICENSE)。
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
<sub>用 ❤️ 为 24/7 编程的开发者打造</sub>
|
||||
<br/>
|
||||
<sub><a href="https://omniroute.online">omniroute.online</a></sub>
|
||||
</div>
|
||||
169
SECURITY.md
Normal file
169
SECURITY.md
Normal file
@@ -0,0 +1,169 @@
|
||||
# Security Policy
|
||||
|
||||
## Reporting Vulnerabilities
|
||||
|
||||
If you discover a security vulnerability in OmniRoute, please report it responsibly:
|
||||
|
||||
1. **DO NOT** open a public GitHub issue
|
||||
2. Use [GitHub Security Advisories](https://github.com/diegosouzapw/OmniRoute/security/advisories/new)
|
||||
3. Include: description, reproduction steps, and potential impact
|
||||
|
||||
## Response Timeline
|
||||
|
||||
| Stage | Target |
|
||||
| ------------------- | --------------------------- |
|
||||
| Acknowledgment | 48 hours |
|
||||
| Triage & Assessment | 5 business days |
|
||||
| Patch Release | 14 business days (critical) |
|
||||
|
||||
## Supported Versions
|
||||
|
||||
| Version | Support Status |
|
||||
| ------- | -------------- |
|
||||
| 0.8.x | ✅ Active |
|
||||
| 0.7.x | ✅ Security |
|
||||
| < 0.7.0 | ❌ Unsupported |
|
||||
|
||||
---
|
||||
|
||||
## Security Architecture
|
||||
|
||||
OmniRoute implements a multi-layered security model:
|
||||
|
||||
```
|
||||
Request → CORS → API Key Auth → Prompt Injection Guard → Input Sanitizer → Rate Limiter → Circuit Breaker → Provider
|
||||
```
|
||||
|
||||
### 🔐 Authentication & Authorization
|
||||
|
||||
| Feature | Implementation |
|
||||
| -------------------- | ---------------------------------------------------------- |
|
||||
| **Dashboard Login** | Password-based auth with JWT tokens (HttpOnly cookies) |
|
||||
| **API Key Auth** | HMAC-signed keys with CRC validation |
|
||||
| **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 |
|
||||
|
||||
### 🛡️ Encryption at Rest
|
||||
|
||||
All sensitive data stored in SQLite is encrypted using **AES-256-GCM** with scrypt key derivation:
|
||||
|
||||
- API keys, access tokens, refresh tokens, and ID tokens
|
||||
- Versioned format: `enc:v1:<iv>:<ciphertext>:<authTag>`
|
||||
- Passthrough mode (plaintext) when `STORAGE_ENCRYPTION_KEY` is not set
|
||||
|
||||
```bash
|
||||
# Generate encryption key:
|
||||
STORAGE_ENCRYPTION_KEY=$(openssl rand -hex 32)
|
||||
```
|
||||
|
||||
### 🧠 Prompt Injection Guard
|
||||
|
||||
Middleware that detects and blocks prompt injection attacks in LLM requests:
|
||||
|
||||
| Pattern Type | Severity | Example |
|
||||
| ------------------- | -------- | ---------------------------------------------- |
|
||||
| System Override | High | "ignore all previous instructions" |
|
||||
| Role Hijack | High | "you are now DAN, you can do anything" |
|
||||
| Delimiter Injection | Medium | Encoded separators to break context boundaries |
|
||||
| DAN/Jailbreak | High | Known jailbreak prompt patterns |
|
||||
| Instruction Leak | Medium | "show me your system prompt" |
|
||||
|
||||
Configure via dashboard (Settings → Security) or `.env`:
|
||||
|
||||
```env
|
||||
INPUT_SANITIZER_ENABLED=true
|
||||
INPUT_SANITIZER_MODE=block # warn | block | redact
|
||||
```
|
||||
|
||||
### 🔒 PII Redaction
|
||||
|
||||
Automatic detection and optional redaction of personally identifiable information:
|
||||
|
||||
| PII Type | Pattern | Replacement |
|
||||
| ------------- | --------------------- | ------------------ |
|
||||
| Email | `user@domain.com` | `[EMAIL_REDACTED]` |
|
||||
| CPF (Brazil) | `123.456.789-00` | `[CPF_REDACTED]` |
|
||||
| CNPJ (Brazil) | `12.345.678/0001-00` | `[CNPJ_REDACTED]` |
|
||||
| Credit Card | `4111-1111-1111-1111` | `[CC_REDACTED]` |
|
||||
| Phone | `+55 11 99999-9999` | `[PHONE_REDACTED]` |
|
||||
| SSN (US) | `123-45-6789` | `[SSN_REDACTED]` |
|
||||
|
||||
```env
|
||||
PII_REDACTION_ENABLED=true
|
||||
```
|
||||
|
||||
### 🌐 Network Security
|
||||
|
||||
| Feature | Description |
|
||||
| ------------------------ | ---------------------------------------------------------------- |
|
||||
| **CORS** | Configurable origin control (`CORS_ORIGIN` env var, default `*`) |
|
||||
| **IP Filtering** | Whitelist/blacklist IP ranges in dashboard |
|
||||
| **Rate Limiting** | Per-provider rate limits with automatic backoff |
|
||||
| **Anti-Thundering Herd** | Mutex + per-connection locking prevents cascading 502s |
|
||||
|
||||
### 🔌 Resilience & Availability
|
||||
|
||||
| Feature | Description |
|
||||
| ----------------------- | ------------------------------------------------------------------ |
|
||||
| **Circuit Breaker** | 3-state (Closed → Open → Half-Open) per provider, SQLite-persisted |
|
||||
| **Request Idempotency** | 5-second dedup window for duplicate requests |
|
||||
| **Exponential Backoff** | Automatic retry with increasing delays |
|
||||
| **Health Dashboard** | Real-time provider health monitoring |
|
||||
|
||||
### 📋 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 |
|
||||
|
||||
---
|
||||
|
||||
## Required Environment Variables
|
||||
|
||||
All secrets must be set before starting the server. The server will **fail fast** if they are missing or weak.
|
||||
|
||||
```bash
|
||||
# REQUIRED — server will not start without these:
|
||||
JWT_SECRET=$(openssl rand -base64 48) # min 32 chars
|
||||
API_KEY_SECRET=$(openssl rand -hex 32) # min 16 chars
|
||||
|
||||
# RECOMMENDED — enables encryption at rest:
|
||||
STORAGE_ENCRYPTION_KEY=$(openssl rand -hex 32)
|
||||
```
|
||||
|
||||
The server actively rejects known-weak values like `changeme`, `secret`, or `password`.
|
||||
|
||||
---
|
||||
|
||||
## Docker Security
|
||||
|
||||
- Use non-root user in production
|
||||
- Mount secrets as read-only volumes
|
||||
- Never copy `.env` files into Docker images
|
||||
- Use `.dockerignore` to exclude sensitive files
|
||||
- Set `AUTH_COOKIE_SECURE=true` when behind HTTPS
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
--name omniroute \
|
||||
--restart unless-stopped \
|
||||
--read-only \
|
||||
-p 20128:20128 \
|
||||
-v omniroute-data:/app/data \
|
||||
-e JWT_SECRET="$(openssl rand -base64 48)" \
|
||||
-e API_KEY_SECRET="$(openssl rand -hex 32)" \
|
||||
-e STORAGE_ENCRYPTION_KEY="$(openssl rand -hex 32)" \
|
||||
diegosouzapw/omniroute:latest
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Run `npm audit` regularly
|
||||
- Keep dependencies updated
|
||||
- The project uses `husky` + `lint-staged` for pre-commit checks
|
||||
- CI pipeline runs ESLint security rules on every push
|
||||
189
bin/omniroute.mjs
Executable file
189
bin/omniroute.mjs
Executable file
@@ -0,0 +1,189 @@
|
||||
#!/usr/bin/env node
|
||||
|
||||
/**
|
||||
* OmniRoute CLI — Smart AI Router with Auto Fallback
|
||||
*
|
||||
* Usage:
|
||||
* omniroute Start the server (default port 20128)
|
||||
* omniroute --port 3000 Start on custom port
|
||||
* omniroute --no-open Start without opening browser
|
||||
* omniroute --help Show help
|
||||
* omniroute --version Show version
|
||||
*/
|
||||
|
||||
import { spawn } from "node:child_process";
|
||||
import { existsSync } from "node:fs";
|
||||
import { join, dirname } from "node:path";
|
||||
import { fileURLToPath } from "node:url";
|
||||
|
||||
const __filename = fileURLToPath(import.meta.url);
|
||||
const __dirname = dirname(__filename);
|
||||
const ROOT = join(__dirname, "..");
|
||||
const APP_DIR = join(ROOT, "app");
|
||||
|
||||
// ── Parse args ─────────────────────────────────────────────
|
||||
const args = process.argv.slice(2);
|
||||
|
||||
if (args.includes("--help") || args.includes("-h")) {
|
||||
console.log(`
|
||||
\x1b[1m\x1b[36m⚡ OmniRoute\x1b[0m — Smart AI Router with Auto Fallback
|
||||
|
||||
\x1b[1mUsage:\x1b[0m
|
||||
omniroute Start the server
|
||||
omniroute --port <port> Use custom port (default: 20128)
|
||||
omniroute --no-open Don't open browser automatically
|
||||
omniroute --help Show this help
|
||||
omniroute --version Show version
|
||||
|
||||
\x1b[1mAfter starting:\x1b[0m
|
||||
Dashboard: http://localhost:<port>
|
||||
API: http://localhost:<port>/v1
|
||||
|
||||
\x1b[1mConnect your tools:\x1b[0m
|
||||
Set your CLI tool (Cursor, Cline, Codex, etc.) to use:
|
||||
\x1b[33mhttp://localhost:20128/v1\x1b[0m
|
||||
`);
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
if (args.includes("--version") || args.includes("-v")) {
|
||||
try {
|
||||
const pkg = await import(join(ROOT, "package.json"), {
|
||||
with: { type: "json" },
|
||||
});
|
||||
console.log(pkg.default.version);
|
||||
} catch {
|
||||
console.log("unknown");
|
||||
}
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
// Parse --port
|
||||
let port = 20128;
|
||||
const portIdx = args.indexOf("--port");
|
||||
if (portIdx !== -1 && args[portIdx + 1]) {
|
||||
port = parseInt(args[portIdx + 1], 10);
|
||||
if (isNaN(port)) {
|
||||
console.error("\x1b[31m✖ Invalid port number\x1b[0m");
|
||||
process.exit(1);
|
||||
}
|
||||
}
|
||||
|
||||
const noOpen = args.includes("--no-open");
|
||||
|
||||
// ── Banner ─────────────────────────────────────────────────
|
||||
console.log(`
|
||||
\x1b[36m ____ _ ____ _
|
||||
/ __ \\ (_) __ \\ | |
|
||||
| | | |_ __ ___ _ __ _| |__) |___ _ _| |_ ___
|
||||
| | | | '_ \` _ \\| '_ \\ | _ // _ \\| | | | __/ _ \\
|
||||
| |__| | | | | | | | | | | | \\ \\ (_) | |_| | || __/
|
||||
\\____/|_| |_| |_|_| |_|_|_| \\_\\___/ \\__,_|\\__\\___|
|
||||
\x1b[0m`);
|
||||
|
||||
// ── Resolve server entry ───────────────────────────────────
|
||||
const serverJs = join(APP_DIR, "server.js");
|
||||
|
||||
if (!existsSync(serverJs)) {
|
||||
console.error(
|
||||
"\x1b[31m✖ Server not found at:\x1b[0m",
|
||||
serverJs,
|
||||
);
|
||||
console.error(
|
||||
" This usually means the package was not built correctly.",
|
||||
);
|
||||
console.error(" Try reinstalling: npm install -g omniroute");
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
// ── Start server ───────────────────────────────────────────
|
||||
console.log(` \x1b[2m⏳ Starting server...\x1b[0m\n`);
|
||||
|
||||
const env = {
|
||||
...process.env,
|
||||
PORT: String(port),
|
||||
HOSTNAME: "0.0.0.0",
|
||||
NODE_ENV: "production",
|
||||
};
|
||||
|
||||
const server = spawn("node", [serverJs], {
|
||||
cwd: APP_DIR,
|
||||
env,
|
||||
stdio: "pipe",
|
||||
});
|
||||
|
||||
let started = false;
|
||||
|
||||
server.stdout.on("data", (data) => {
|
||||
const text = data.toString();
|
||||
process.stdout.write(text);
|
||||
|
||||
// Detect server ready
|
||||
if (!started && (text.includes("Ready") || text.includes("started") || text.includes("listening"))) {
|
||||
started = true;
|
||||
onReady();
|
||||
}
|
||||
});
|
||||
|
||||
server.stderr.on("data", (data) => {
|
||||
process.stderr.write(data);
|
||||
});
|
||||
|
||||
server.on("error", (err) => {
|
||||
console.error("\x1b[31m✖ Failed to start server:\x1b[0m", err.message);
|
||||
process.exit(1);
|
||||
});
|
||||
|
||||
server.on("exit", (code) => {
|
||||
if (code !== 0 && code !== null) {
|
||||
console.error(`\x1b[31m✖ Server exited with code ${code}\x1b[0m`);
|
||||
}
|
||||
process.exit(code ?? 0);
|
||||
});
|
||||
|
||||
// ── Graceful shutdown ──────────────────────────────────────
|
||||
function shutdown() {
|
||||
console.log("\n\x1b[33m⏹ Shutting down OmniRoute...\x1b[0m");
|
||||
server.kill("SIGTERM");
|
||||
setTimeout(() => {
|
||||
server.kill("SIGKILL");
|
||||
process.exit(0);
|
||||
}, 5000);
|
||||
}
|
||||
|
||||
process.on("SIGINT", shutdown);
|
||||
process.on("SIGTERM", shutdown);
|
||||
|
||||
// ── On ready ───────────────────────────────────────────────
|
||||
async function onReady() {
|
||||
const url = `http://localhost:${port}`;
|
||||
|
||||
console.log(`
|
||||
\x1b[32m✔ OmniRoute is running!\x1b[0m
|
||||
|
||||
\x1b[1m Dashboard:\x1b[0m ${url}
|
||||
\x1b[1m API Base:\x1b[0m ${url}/v1
|
||||
|
||||
\x1b[2m Point your CLI tool (Cursor, Cline, Codex) to:\x1b[0m
|
||||
\x1b[33m ${url}/v1\x1b[0m
|
||||
|
||||
\x1b[2m Press Ctrl+C to stop\x1b[0m
|
||||
`);
|
||||
|
||||
if (!noOpen) {
|
||||
try {
|
||||
const open = await import("open");
|
||||
await open.default(url);
|
||||
} catch {
|
||||
// open is optional — if not available, just skip
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Fallback: if no "Ready" message detected in 15s, assume server is up
|
||||
setTimeout(() => {
|
||||
if (!started) {
|
||||
started = true;
|
||||
onReady();
|
||||
}
|
||||
}, 15000);
|
||||
116
bin/reset-password.mjs
Normal file
116
bin/reset-password.mjs
Normal file
@@ -0,0 +1,116 @@
|
||||
#!/usr/bin/env node
|
||||
|
||||
/**
|
||||
* Password Reset CLI — T-38
|
||||
*
|
||||
* Usage:
|
||||
* node bin/reset-password.mjs
|
||||
* npx omniroute reset-password
|
||||
*
|
||||
* Resets the admin password for OmniRoute.
|
||||
* Prompts for a new password and updates the database directly.
|
||||
*
|
||||
* @module bin/reset-password
|
||||
*/
|
||||
|
||||
import { createInterface } from "node:readline";
|
||||
import { resolve, dirname } from "node:path";
|
||||
import { fileURLToPath } from "node:url";
|
||||
import { existsSync } from "node:fs";
|
||||
import { createHash } from "node:crypto";
|
||||
|
||||
const __dirname = dirname(fileURLToPath(import.meta.url));
|
||||
|
||||
// Resolve data directory — same logic as the server
|
||||
const DATA_DIR = process.env.DATA_DIR || resolve(__dirname, "..", "data");
|
||||
const DB_PATH = resolve(DATA_DIR, "settings.db");
|
||||
|
||||
const rl = createInterface({
|
||||
input: process.stdin,
|
||||
output: process.stdout,
|
||||
});
|
||||
|
||||
function ask(question) {
|
||||
return new Promise((resolve) => rl.question(question, resolve));
|
||||
}
|
||||
|
||||
function hashPassword(password) {
|
||||
return createHash("sha256").update(password).digest("hex");
|
||||
}
|
||||
|
||||
console.log("\n🔑 OmniRoute — Password Reset\n");
|
||||
|
||||
async function main() {
|
||||
// Check if database exists
|
||||
if (!existsSync(DB_PATH)) {
|
||||
console.error(`❌ Database not found at: ${DB_PATH}`);
|
||||
console.error(` Make sure OmniRoute has been started at least once.`);
|
||||
console.error(` Or set DATA_DIR env var to your data directory.\n`);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
let Database;
|
||||
try {
|
||||
Database = (await import("better-sqlite3")).default;
|
||||
} catch {
|
||||
console.error("❌ better-sqlite3 not installed. Run: npm install");
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
const db = new Database(DB_PATH);
|
||||
|
||||
// Check current settings
|
||||
const row = db.prepare("SELECT value FROM settings WHERE key = 'password'").get();
|
||||
|
||||
if (row) {
|
||||
console.log("ℹ️ A password is currently set.");
|
||||
} else {
|
||||
console.log("ℹ️ No password is currently set.");
|
||||
}
|
||||
|
||||
const password = await ask("Enter new password (min 4 chars): ");
|
||||
|
||||
if (!password || password.length < 4) {
|
||||
console.error("\n❌ Password must be at least 4 characters.\n");
|
||||
db.close();
|
||||
rl.close();
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
const confirm = await ask("Confirm new password: ");
|
||||
|
||||
if (password !== confirm) {
|
||||
console.error("\n❌ Passwords do not match.\n");
|
||||
db.close();
|
||||
rl.close();
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
const hashed = hashPassword(password);
|
||||
|
||||
// Upsert the password
|
||||
const stmt = db.prepare(`
|
||||
INSERT INTO settings (key, value) VALUES ('password', ?)
|
||||
ON CONFLICT(key) DO UPDATE SET value = excluded.value
|
||||
`);
|
||||
stmt.run(hashed);
|
||||
|
||||
// Also ensure requireLogin is true
|
||||
const loginStmt = db.prepare(`
|
||||
INSERT INTO settings (key, value) VALUES ('requireLogin', 'true')
|
||||
ON CONFLICT(key) DO UPDATE SET value = excluded.value
|
||||
`);
|
||||
loginStmt.run();
|
||||
|
||||
db.close();
|
||||
rl.close();
|
||||
|
||||
console.log("\n✅ Password reset successfully!");
|
||||
console.log(" Restart OmniRoute for changes to take effect.\n");
|
||||
}
|
||||
|
||||
main().catch((err) => {
|
||||
console.error(`\n❌ Error: ${err.message}\n`);
|
||||
rl.close();
|
||||
process.exit(1);
|
||||
});
|
||||
47
docker-compose.prod.yml
Normal file
47
docker-compose.prod.yml
Normal file
@@ -0,0 +1,47 @@
|
||||
# ──────────────────────────────────────────────────────────────────────
|
||||
# OmniRoute — Docker Compose (Production Snapshot)
|
||||
# ──────────────────────────────────────────────────────────────────────
|
||||
#
|
||||
# Isolated production instance running on port 20130.
|
||||
# Keeps the app running while you continue developing locally.
|
||||
#
|
||||
# Usage:
|
||||
# docker compose -f docker-compose.prod.yml up -d --build
|
||||
# docker compose -f docker-compose.prod.yml down
|
||||
# docker compose -f docker-compose.prod.yml logs -f
|
||||
# ──────────────────────────────────────────────────────────────────────
|
||||
|
||||
services:
|
||||
omniroute-prod:
|
||||
container_name: omniroute-prod
|
||||
build:
|
||||
context: .
|
||||
target: runner-base
|
||||
image: omniroute:prod
|
||||
restart: unless-stopped
|
||||
env_file: .env
|
||||
environment:
|
||||
- NODE_ENV=production
|
||||
- PORT=20128
|
||||
- HOSTNAME=0.0.0.0
|
||||
- DATA_DIR=/app/data
|
||||
ports:
|
||||
- "20130:20128"
|
||||
volumes:
|
||||
- omniroute-prod-data:/app/data
|
||||
healthcheck:
|
||||
test:
|
||||
[
|
||||
"CMD",
|
||||
"node",
|
||||
"-e",
|
||||
"fetch('http://127.0.0.1:20128/api/settings').then(r=>{if(!r.ok)throw r.status}).catch(()=>process.exit(1))",
|
||||
]
|
||||
interval: 30s
|
||||
timeout: 5s
|
||||
retries: 3
|
||||
start_period: 15s
|
||||
|
||||
volumes:
|
||||
omniroute-prod-data:
|
||||
name: omniroute-prod-data
|
||||
101
docker-compose.yml
Normal file
101
docker-compose.yml
Normal file
@@ -0,0 +1,101 @@
|
||||
# ──────────────────────────────────────────────────────────────────────
|
||||
# OmniRoute — Docker Compose
|
||||
# ──────────────────────────────────────────────────────────────────────
|
||||
#
|
||||
# Profiles:
|
||||
# base → minimal image, no CLI tools
|
||||
# cli → CLIs installed inside the container (portable)
|
||||
# host → runner-base + host-mounted CLI binaries (Linux-first)
|
||||
#
|
||||
# Usage:
|
||||
# docker compose --profile base up -d
|
||||
# docker compose --profile cli up -d
|
||||
# docker compose --profile host up -d
|
||||
#
|
||||
# Before first run, copy .env.example → .env and edit your secrets.
|
||||
# ──────────────────────────────────────────────────────────────────────
|
||||
|
||||
x-common: &common
|
||||
restart: unless-stopped
|
||||
env_file: .env
|
||||
volumes:
|
||||
- omniroute-data:/app/data
|
||||
healthcheck:
|
||||
test:
|
||||
[
|
||||
"CMD",
|
||||
"node",
|
||||
"-e",
|
||||
"fetch('http://127.0.0.1:20128/api/settings').then(r=>{if(!r.ok)throw r.status}).catch(()=>process.exit(1))",
|
||||
]
|
||||
interval: 30s
|
||||
timeout: 5s
|
||||
retries: 3
|
||||
start_period: 15s
|
||||
|
||||
services:
|
||||
# ── Profile: base (minimal, no CLI tools) ──────────────────────────
|
||||
omniroute-base:
|
||||
<<: *common
|
||||
container_name: omniroute
|
||||
build:
|
||||
context: .
|
||||
target: runner-base
|
||||
image: omniroute:base
|
||||
ports:
|
||||
- "${PORT:-20128}:20128"
|
||||
profiles:
|
||||
- base
|
||||
|
||||
# ── Profile: cli (CLIs installed inside container) ─────────────────
|
||||
omniroute-cli:
|
||||
<<: *common
|
||||
container_name: omniroute
|
||||
build:
|
||||
context: .
|
||||
target: runner-cli
|
||||
image: omniroute:cli
|
||||
ports:
|
||||
- "${PORT:-20128}:20128"
|
||||
profiles:
|
||||
- cli
|
||||
|
||||
# ── Profile: host (host-mounted CLI binaries, Linux-first) ────────
|
||||
omniroute-host:
|
||||
<<: *common
|
||||
container_name: omniroute
|
||||
build:
|
||||
context: .
|
||||
target: runner-base
|
||||
image: omniroute:base
|
||||
ports:
|
||||
- "${PORT:-20128}:20128"
|
||||
environment:
|
||||
- CLI_MODE=host
|
||||
- CLI_EXTRA_PATHS=/host-local/bin:/host-node/bin
|
||||
- CLI_CONFIG_HOME=/host-home
|
||||
- CLI_ALLOW_CONFIG_WRITES=true
|
||||
# Uncomment per-tool overrides as needed:
|
||||
# - CLI_CURSOR_BIN=agent
|
||||
# - CLI_CLINE_BIN=cline
|
||||
# - CLI_CONTINUE_BIN=cn
|
||||
volumes:
|
||||
- omniroute-data:/app/data
|
||||
# ── Host binary mounts (read-only) ──
|
||||
# Adjust paths below to match YOUR host system.
|
||||
- ~/.local/bin:/host-local/bin:ro
|
||||
# Node global binaries (adjust node version path)
|
||||
# - ~/.nvm/versions/node/v22.16.0/bin:/host-node/bin:ro
|
||||
# ── Host config mounts (read-write) ──
|
||||
- ~/.codex:/host-home/.codex:rw
|
||||
- ~/.claude:/host-home/.claude:rw
|
||||
- ~/.factory:/host-home/.factory:rw
|
||||
- ~/.openclaw:/host-home/.openclaw:rw
|
||||
- ~/.cursor:/host-home/.cursor:rw
|
||||
- ~/.config/cursor:/host-home/.config/cursor:rw
|
||||
profiles:
|
||||
- host
|
||||
|
||||
volumes:
|
||||
omniroute-data:
|
||||
name: omniroute-data
|
||||
439
docs/API_REFERENCE.md
Normal file
439
docs/API_REFERENCE.md
Normal file
@@ -0,0 +1,439 @@
|
||||
# API Reference
|
||||
|
||||
Complete reference for all OmniRoute API endpoints.
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Chat Completions](#chat-completions)
|
||||
- [Embeddings](#embeddings)
|
||||
- [Image Generation](#image-generation)
|
||||
- [List Models](#list-models)
|
||||
- [Compatibility Endpoints](#compatibility-endpoints)
|
||||
- [Semantic Cache](#semantic-cache)
|
||||
- [Dashboard & Management](#dashboard--management)
|
||||
- [Request Processing](#request-processing)
|
||||
- [Authentication](#authentication)
|
||||
|
||||
---
|
||||
|
||||
## Chat Completions
|
||||
|
||||
```bash
|
||||
POST /v1/chat/completions
|
||||
Authorization: Bearer your-api-key
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"model": "cc/claude-opus-4-6",
|
||||
"messages": [
|
||||
{"role": "user", "content": "Write a function to..."}
|
||||
],
|
||||
"stream": true
|
||||
}
|
||||
```
|
||||
|
||||
### Custom Headers
|
||||
|
||||
| Header | Direction | Description |
|
||||
| ------------------------ | --------- | --------------------------------- |
|
||||
| `X-OmniRoute-No-Cache` | Request | Set to `true` to bypass cache |
|
||||
| `X-OmniRoute-Progress` | Request | Set to `true` for progress events |
|
||||
| `Idempotency-Key` | Request | Dedup key (5s window) |
|
||||
| `X-Request-Id` | Request | Alternative dedup key |
|
||||
| `X-OmniRoute-Cache` | Response | `HIT` or `MISS` (non-streaming) |
|
||||
| `X-OmniRoute-Idempotent` | Response | `true` if deduplicated |
|
||||
| `X-OmniRoute-Progress` | Response | `enabled` if progress tracking on |
|
||||
|
||||
---
|
||||
|
||||
## Embeddings
|
||||
|
||||
```bash
|
||||
POST /v1/embeddings
|
||||
Authorization: Bearer your-api-key
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"model": "nebius/Qwen/Qwen3-Embedding-8B",
|
||||
"input": "The food was delicious"
|
||||
}
|
||||
```
|
||||
|
||||
Available providers: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA.
|
||||
|
||||
```bash
|
||||
# List all embedding models
|
||||
GET /v1/embeddings
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Image Generation
|
||||
|
||||
```bash
|
||||
POST /v1/images/generations
|
||||
Authorization: Bearer your-api-key
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"model": "openai/dall-e-3",
|
||||
"prompt": "A beautiful sunset over mountains",
|
||||
"size": "1024x1024"
|
||||
}
|
||||
```
|
||||
|
||||
Available providers: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI.
|
||||
|
||||
```bash
|
||||
# List all image models
|
||||
GET /v1/images/generations
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## List Models
|
||||
|
||||
```bash
|
||||
GET /v1/models
|
||||
Authorization: Bearer your-api-key
|
||||
|
||||
→ Returns all chat, embedding, and image models + combos in OpenAI format
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Compatibility Endpoints
|
||||
|
||||
| Method | Path | Format |
|
||||
| ------ | --------------------------- | ---------------------- |
|
||||
| POST | `/v1/chat/completions` | OpenAI |
|
||||
| POST | `/v1/messages` | Anthropic |
|
||||
| POST | `/v1/responses` | OpenAI Responses |
|
||||
| POST | `/v1/embeddings` | OpenAI |
|
||||
| POST | `/v1/images/generations` | OpenAI |
|
||||
| GET | `/v1/models` | OpenAI |
|
||||
| POST | `/v1/messages/count_tokens` | Anthropic |
|
||||
| GET | `/v1beta/models` | Gemini |
|
||||
| POST | `/v1beta/models/{...path}` | Gemini generateContent |
|
||||
| POST | `/v1/api/chat` | Ollama |
|
||||
|
||||
### Dedicated Provider Routes
|
||||
|
||||
```bash
|
||||
POST /v1/providers/{provider}/chat/completions
|
||||
POST /v1/providers/{provider}/embeddings
|
||||
POST /v1/providers/{provider}/images/generations
|
||||
```
|
||||
|
||||
The provider prefix is auto-added if missing. Mismatched models return `400`.
|
||||
|
||||
---
|
||||
|
||||
## Semantic Cache
|
||||
|
||||
```bash
|
||||
# Get cache stats
|
||||
GET /api/cache
|
||||
|
||||
# Clear all caches
|
||||
DELETE /api/cache
|
||||
```
|
||||
|
||||
Response example:
|
||||
|
||||
```json
|
||||
{
|
||||
"semanticCache": {
|
||||
"memorySize": 42,
|
||||
"memoryMaxSize": 500,
|
||||
"dbSize": 128,
|
||||
"hitRate": 0.65
|
||||
},
|
||||
"idempotency": {
|
||||
"activeKeys": 3,
|
||||
"windowMs": 5000
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Dashboard & Management
|
||||
|
||||
### Authentication
|
||||
|
||||
| Endpoint | Method | Description |
|
||||
| ----------------------------- | ------- | --------------------- |
|
||||
| `/api/auth/login` | POST | Login |
|
||||
| `/api/auth/logout` | POST | Logout |
|
||||
| `/api/settings/require-login` | GET/PUT | Toggle login required |
|
||||
|
||||
### Provider Management
|
||||
|
||||
| Endpoint | Method | Description |
|
||||
| ---------------------------- | --------------- | ------------------------ |
|
||||
| `/api/providers` | GET/POST | List / create providers |
|
||||
| `/api/providers/[id]` | GET/PUT/DELETE | Manage a provider |
|
||||
| `/api/providers/[id]/test` | POST | Test provider connection |
|
||||
| `/api/providers/[id]/models` | GET | List provider models |
|
||||
| `/api/providers/validate` | POST | Validate provider config |
|
||||
| `/api/provider-nodes*` | Various | Provider node management |
|
||||
| `/api/provider-models` | GET/POST/DELETE | Custom models |
|
||||
|
||||
### OAuth Flows
|
||||
|
||||
| Endpoint | Method | Description |
|
||||
| -------------------------------- | ------- | ----------------------- |
|
||||
| `/api/oauth/[provider]/[action]` | Various | Provider-specific OAuth |
|
||||
|
||||
### Routing & Config
|
||||
|
||||
| Endpoint | Method | Description |
|
||||
| --------------------- | -------- | ----------------------------- |
|
||||
| `/api/models/alias` | GET/POST | Model aliases |
|
||||
| `/api/models/catalog` | GET | All models by provider + type |
|
||||
| `/api/combos*` | Various | Combo management |
|
||||
| `/api/keys*` | Various | API key management |
|
||||
| `/api/pricing` | GET | Model pricing |
|
||||
|
||||
### Usage & Analytics
|
||||
|
||||
| Endpoint | Method | Description |
|
||||
| --------------------------- | ------ | -------------------- |
|
||||
| `/api/usage/history` | GET | Usage history |
|
||||
| `/api/usage/logs` | GET | Usage logs |
|
||||
| `/api/usage/request-logs` | GET | Request-level logs |
|
||||
| `/api/usage/[connectionId]` | GET | Per-connection usage |
|
||||
|
||||
### Settings
|
||||
|
||||
| Endpoint | Method | Description |
|
||||
| ------------------------------- | ------- | ---------------------- |
|
||||
| `/api/settings` | GET/PUT | General settings |
|
||||
| `/api/settings/proxy` | GET/PUT | Network proxy config |
|
||||
| `/api/settings/proxy/test` | POST | Test proxy connection |
|
||||
| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist |
|
||||
| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget |
|
||||
| `/api/settings/system-prompt` | GET/PUT | Global system prompt |
|
||||
|
||||
### Monitoring
|
||||
|
||||
| Endpoint | Method | Description |
|
||||
| ------------------------ | ---------- | ----------------------- |
|
||||
| `/api/sessions` | GET | Active session tracking |
|
||||
| `/api/rate-limits` | GET | Per-account rate limits |
|
||||
| `/api/monitoring/health` | GET | Health check |
|
||||
| `/api/cache` | GET/DELETE | Cache stats / clear |
|
||||
|
||||
### Backup & Export/Import
|
||||
|
||||
| Endpoint | Method | Description |
|
||||
| --------------------------- | ------ | --------------------------------------- |
|
||||
| `/api/db-backups` | GET | List available backups |
|
||||
| `/api/db-backups` | PUT | Create a manual backup |
|
||||
| `/api/db-backups` | POST | Restore from a specific backup |
|
||||
| `/api/db-backups/export` | GET | Download database as .sqlite file |
|
||||
| `/api/db-backups/import` | POST | Upload .sqlite file to replace database |
|
||||
| `/api/db-backups/exportAll` | GET | Download full backup as .tar.gz archive |
|
||||
|
||||
### Cloud Sync
|
||||
|
||||
| Endpoint | Method | Description |
|
||||
| ---------------------- | ------- | --------------------- |
|
||||
| `/api/sync/cloud` | Various | Cloud sync operations |
|
||||
| `/api/sync/initialize` | POST | Initialize sync |
|
||||
| `/api/cloud/*` | Various | Cloud management |
|
||||
|
||||
### CLI Tools
|
||||
|
||||
| Endpoint | Method | Description |
|
||||
| ---------------------------------- | ------ | ------------------- |
|
||||
| `/api/cli-tools/claude-settings` | GET | Claude CLI status |
|
||||
| `/api/cli-tools/codex-settings` | GET | Codex CLI status |
|
||||
| `/api/cli-tools/droid-settings` | GET | Droid CLI status |
|
||||
| `/api/cli-tools/openclaw-settings` | GET | OpenClaw CLI status |
|
||||
| `/api/cli-tools/runtime/[toolId]` | GET | Generic CLI runtime |
|
||||
|
||||
CLI responses include: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`.
|
||||
|
||||
### Resilience & Rate Limits
|
||||
|
||||
| Endpoint | Method | Description |
|
||||
| ----------------------- | ------- | ------------------------------- |
|
||||
| `/api/resilience` | GET/PUT | Get/update resilience profiles |
|
||||
| `/api/resilience/reset` | POST | Reset circuit breakers |
|
||||
| `/api/rate-limits` | GET | Per-account rate limit status |
|
||||
| `/api/rate-limit` | GET | Global rate limit configuration |
|
||||
|
||||
### Evals
|
||||
|
||||
| Endpoint | Method | Description |
|
||||
| ------------ | -------- | --------------------------------- |
|
||||
| `/api/evals` | GET/POST | List eval suites / run evaluation |
|
||||
|
||||
### Policies
|
||||
|
||||
| Endpoint | Method | Description |
|
||||
| --------------- | --------------- | ----------------------- |
|
||||
| `/api/policies` | GET/POST/DELETE | Manage routing policies |
|
||||
|
||||
### Compliance
|
||||
|
||||
| Endpoint | Method | Description |
|
||||
| --------------------------- | ------ | ----------------------------- |
|
||||
| `/api/compliance/audit-log` | GET | Compliance audit log (last N) |
|
||||
|
||||
### v1beta (Gemini-Compatible)
|
||||
|
||||
| Endpoint | Method | Description |
|
||||
| -------------------------- | ------ | --------------------------------- |
|
||||
| `/v1beta/models` | GET | List models in Gemini format |
|
||||
| `/v1beta/models/{...path}` | POST | Gemini `generateContent` endpoint |
|
||||
|
||||
These endpoints mirror Gemini's API format for clients that expect native Gemini SDK compatibility.
|
||||
|
||||
### Internal / System APIs
|
||||
|
||||
| Endpoint | Method | Description |
|
||||
| --------------- | ------ | ---------------------------------------------------- |
|
||||
| `/api/init` | GET | Application initialization check (used on first run) |
|
||||
| `/api/tags` | GET | Ollama-compatible model tags (for Ollama clients) |
|
||||
| `/api/restart` | POST | Trigger graceful server restart |
|
||||
| `/api/shutdown` | POST | Trigger graceful server shutdown |
|
||||
|
||||
> **Note:** These endpoints are used internally by the system or for Ollama client compatibility. They are not typically called by end users.
|
||||
|
||||
---
|
||||
|
||||
## Audio Transcription
|
||||
|
||||
```bash
|
||||
POST /v1/audio/transcriptions
|
||||
Authorization: Bearer your-api-key
|
||||
Content-Type: multipart/form-data
|
||||
```
|
||||
|
||||
Transcribe audio files using Deepgram or AssemblyAI.
|
||||
|
||||
**Request:**
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:20128/v1/audio/transcriptions \
|
||||
-H "Authorization: Bearer your-api-key" \
|
||||
-F "file=@recording.mp3" \
|
||||
-F "model=deepgram/nova-3"
|
||||
```
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"text": "Hello, this is the transcribed audio content.",
|
||||
"task": "transcribe",
|
||||
"language": "en",
|
||||
"duration": 12.5
|
||||
}
|
||||
```
|
||||
|
||||
**Supported providers:** `deepgram/nova-3`, `assemblyai/best`.
|
||||
|
||||
**Supported formats:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
|
||||
|
||||
---
|
||||
|
||||
## Ollama Compatibility
|
||||
|
||||
For clients that use Ollama's API format:
|
||||
|
||||
```bash
|
||||
# Chat endpoint (Ollama format)
|
||||
POST /v1/api/chat
|
||||
|
||||
# Model listing (Ollama format)
|
||||
GET /api/tags
|
||||
```
|
||||
|
||||
Requests are automatically translated between Ollama and internal formats.
|
||||
|
||||
---
|
||||
|
||||
## Telemetry
|
||||
|
||||
```bash
|
||||
# Get latency telemetry summary (p50/p95/p99 per provider)
|
||||
GET /api/telemetry/summary
|
||||
```
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"providers": {
|
||||
"claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 },
|
||||
"github": { "p50": 180, "p95": 620, "p99": 950, "count": 320 }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Budget
|
||||
|
||||
```bash
|
||||
# Get budget status for all API keys
|
||||
GET /api/usage/budget
|
||||
|
||||
# Set or update a budget
|
||||
POST /api/usage/budget
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"keyId": "key-123",
|
||||
"limit": 50.00,
|
||||
"period": "monthly"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Model Availability
|
||||
|
||||
```bash
|
||||
# Get real-time model availability across all providers
|
||||
GET /api/models/availability
|
||||
|
||||
# Check availability for a specific model
|
||||
POST /api/models/availability
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"model": "claude-sonnet-4-5-20250929"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Request Processing
|
||||
|
||||
1. Client sends request to `/v1/*`
|
||||
2. Route handler calls `handleChat`, `handleEmbedding`, `handleAudioTranscription`, or `handleImageGeneration`
|
||||
3. Model is resolved (direct provider/model or alias/combo)
|
||||
4. Credentials selected from local DB with account availability filtering
|
||||
5. For chat: `handleChatCore` — format detection, translation, cache check, idempotency check
|
||||
6. Provider executor sends upstream request
|
||||
7. Response translated back to client format (chat) or returned as-is (embeddings/images/audio)
|
||||
8. Usage/logging recorded
|
||||
9. Fallback applies on errors according to combo rules
|
||||
|
||||
Full architecture reference: [`ARCHITECTURE.md`](ARCHITECTURE.md)
|
||||
|
||||
---
|
||||
|
||||
## Authentication
|
||||
|
||||
- Dashboard routes (`/dashboard/*`) use `auth_token` cookie
|
||||
- Login uses saved password hash; fallback to `INITIAL_PASSWORD`
|
||||
- `requireLogin` toggleable via `/api/settings/require-login`
|
||||
- `/v1/*` routes optionally require Bearer API key when `REQUIRE_API_KEY=true`
|
||||
767
docs/ARCHITECTURE.md
Normal file
767
docs/ARCHITECTURE.md
Normal file
@@ -0,0 +1,767 @@
|
||||
# OmniRoute Architecture
|
||||
|
||||
_Last updated: 2026-02-17_
|
||||
|
||||
## Executive Summary
|
||||
|
||||
OmniRoute is a local AI routing gateway and dashboard built on Next.js.
|
||||
It provides a single OpenAI-compatible endpoint (`/v1/*`) and routes traffic across multiple upstream providers with translation, fallback, token refresh, and usage tracking.
|
||||
|
||||
Core capabilities:
|
||||
|
||||
- OpenAI-compatible API surface for CLI/tools (28 providers)
|
||||
- Request/response translation across provider formats
|
||||
- Model combo fallback (multi-model sequence)
|
||||
- Account-level fallback (multi-account per provider)
|
||||
- OAuth + API-key provider connection management
|
||||
- Embedding generation via `/v1/embeddings` (6 providers, 9 models)
|
||||
- Image generation via `/v1/images/generations` (4 providers, 9 models)
|
||||
- Think tag parsing (`<think>...</think>`) for reasoning models
|
||||
- Local persistence for providers, keys, aliases, combos, settings, pricing
|
||||
- Usage/cost tracking and request logging
|
||||
- Optional cloud sync for multi-device/state sync
|
||||
- IP allowlist/blocklist for API access control
|
||||
- Thinking budget management (passthrough/auto/custom/adaptive)
|
||||
- Global system prompt injection
|
||||
- Session tracking and fingerprinting
|
||||
- Per-account enhanced rate limiting with provider-specific profiles
|
||||
- Circuit breaker pattern for provider resilience
|
||||
- Anti-thundering herd protection with mutex locking
|
||||
- Signature-based request deduplication cache
|
||||
- Domain layer: model availability, cost rules, fallback policy, lockout policy
|
||||
- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers)
|
||||
- Policy engine for centralized request evaluation (lockout → budget → fallback)
|
||||
- Request telemetry with p50/p95/p99 latency aggregation
|
||||
- Correlation ID (X-Request-Id) for end-to-end tracing
|
||||
- Compliance audit logging with opt-out per API key
|
||||
- Eval framework for LLM quality assurance
|
||||
- Resilience UI dashboard with real-time circuit breaker status
|
||||
- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`)
|
||||
|
||||
Primary runtime model:
|
||||
|
||||
- Next.js app routes under `src/app/api/*` implement both dashboard APIs and compatibility APIs
|
||||
- A shared SSE/routing core in `src/sse/*` + `open-sse/*` handles provider execution, translation, streaming, fallback, and usage
|
||||
|
||||
## Scope and Boundaries
|
||||
|
||||
### In Scope
|
||||
|
||||
- Local gateway runtime
|
||||
- Dashboard management APIs
|
||||
- Provider authentication and token refresh
|
||||
- Request translation and SSE streaming
|
||||
- Local state + usage persistence
|
||||
- Optional cloud sync orchestration
|
||||
|
||||
### Out of Scope
|
||||
|
||||
- Cloud service implementation behind `NEXT_PUBLIC_CLOUD_URL`
|
||||
- Provider SLA/control plane outside local process
|
||||
- External CLI binaries themselves (Claude CLI, Codex CLI, etc.)
|
||||
|
||||
## High-Level System Context
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
subgraph Clients[Developer Clients]
|
||||
C1[Claude Code]
|
||||
C2[Codex CLI]
|
||||
C3[OpenClaw / Droid / Cline / Continue / Roo]
|
||||
C4[Custom OpenAI-compatible clients]
|
||||
BROWSER[Browser Dashboard]
|
||||
end
|
||||
|
||||
subgraph Router[OmniRoute Local Process]
|
||||
API[V1 Compatibility API\n/v1/*]
|
||||
DASH[Dashboard + Management API\n/api/*]
|
||||
CORE[SSE + Translation Core\nopen-sse + src/sse]
|
||||
DB[(db.json)]
|
||||
UDB[(usage.json + log.txt)]
|
||||
end
|
||||
|
||||
subgraph Upstreams[Upstream Providers]
|
||||
P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/iFlow/GitHub/Kiro/Cursor/Antigravity]
|
||||
P2[API Key Providers\nOpenAI/Anthropic/OpenRouter/GLM/Kimi/MiniMax\nDeepSeek/Groq/xAI/Mistral/Perplexity\nTogether/Fireworks/Cerebras/Cohere/NVIDIA]
|
||||
P3[Compatible Nodes\nOpenAI-compatible / Anthropic-compatible]
|
||||
end
|
||||
|
||||
subgraph Cloud[Optional Cloud Sync]
|
||||
CLOUD[Cloud Sync Endpoint\nNEXT_PUBLIC_CLOUD_URL]
|
||||
end
|
||||
|
||||
C1 --> API
|
||||
C2 --> API
|
||||
C3 --> API
|
||||
C4 --> API
|
||||
BROWSER --> DASH
|
||||
|
||||
API --> CORE
|
||||
DASH --> DB
|
||||
CORE --> DB
|
||||
CORE --> UDB
|
||||
|
||||
CORE --> P1
|
||||
CORE --> P2
|
||||
CORE --> P3
|
||||
|
||||
DASH --> CLOUD
|
||||
```
|
||||
|
||||
## Core Runtime Components
|
||||
|
||||
## 1) API and Routing Layer (Next.js App Routes)
|
||||
|
||||
Main directories:
|
||||
|
||||
- `src/app/api/v1/*` and `src/app/api/v1beta/*` for compatibility APIs
|
||||
- `src/app/api/*` for management/configuration APIs
|
||||
- Next rewrites in `next.config.mjs` map `/v1/*` to `/api/v1/*`
|
||||
|
||||
Important compatibility routes:
|
||||
|
||||
- `src/app/api/v1/chat/completions/route.ts`
|
||||
- `src/app/api/v1/messages/route.ts`
|
||||
- `src/app/api/v1/responses/route.ts`
|
||||
- `src/app/api/v1/models/route.ts` — includes custom models with `custom: true`
|
||||
- `src/app/api/v1/embeddings/route.ts` — embedding generation (6 providers)
|
||||
- `src/app/api/v1/images/generations/route.ts` — image generation (4+ providers incl. Antigravity/Nebius)
|
||||
- `src/app/api/v1/messages/count_tokens/route.ts`
|
||||
- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — dedicated per-provider chat
|
||||
- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — dedicated per-provider embeddings
|
||||
- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — dedicated per-provider images
|
||||
- `src/app/api/v1beta/models/route.ts`
|
||||
- `src/app/api/v1beta/models/[...path]/route.ts`
|
||||
|
||||
Management domains:
|
||||
|
||||
- Auth/settings: `src/app/api/auth/*`, `src/app/api/settings/*`
|
||||
- Providers/connections: `src/app/api/providers*`
|
||||
- Provider nodes: `src/app/api/provider-nodes*`
|
||||
- Custom models: `src/app/api/provider-models` (GET/POST/DELETE)
|
||||
- Model catalog: `src/app/api/models/catalog` (GET)
|
||||
- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST)
|
||||
- OAuth: `src/app/api/oauth/*`
|
||||
- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing`
|
||||
- Usage: `src/app/api/usage/*`
|
||||
- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*`
|
||||
- CLI tooling helpers: `src/app/api/cli-tools/*`
|
||||
- IP filter: `src/app/api/settings/ip-filter` (GET/PUT)
|
||||
- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT)
|
||||
- System prompt: `src/app/api/settings/system-prompt` (GET/PUT)
|
||||
- Sessions: `src/app/api/sessions` (GET)
|
||||
- Rate limits: `src/app/api/rate-limits` (GET)
|
||||
- Resilience: `src/app/api/resilience` (GET/PATCH) — provider profiles, circuit breaker, rate limit state
|
||||
- Resilience reset: `src/app/api/resilience/reset` (POST) — reset breakers + cooldowns
|
||||
- Cache stats: `src/app/api/cache/stats` (GET/DELETE)
|
||||
- Model availability: `src/app/api/models/availability` (GET/POST)
|
||||
- Telemetry: `src/app/api/telemetry/summary` (GET)
|
||||
- Budget: `src/app/api/usage/budget` (GET/POST)
|
||||
- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE)
|
||||
- Compliance audit: `src/app/api/compliance/audit-log` (GET)
|
||||
- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET)
|
||||
- Policies: `src/app/api/policies` (GET/POST)
|
||||
|
||||
## 2) SSE + Translation Core
|
||||
|
||||
Main flow modules:
|
||||
|
||||
- Entry: `src/sse/handlers/chat.ts`
|
||||
- Core orchestration: `open-sse/handlers/chatCore.ts`
|
||||
- Provider execution adapters: `open-sse/executors/*`
|
||||
- Format detection/provider config: `open-sse/services/provider.ts`
|
||||
- Model parse/resolve: `src/sse/services/model.ts`, `open-sse/services/model.ts`
|
||||
- Account fallback logic: `open-sse/services/accountFallback.ts`
|
||||
- Translation registry: `open-sse/translator/index.ts`
|
||||
- Stream transformations: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts`
|
||||
- Usage extraction/normalization: `open-sse/utils/usageTracking.ts`
|
||||
- Think tag parser: `open-sse/utils/thinkTagParser.ts`
|
||||
- Embedding handler: `open-sse/handlers/embeddings.ts`
|
||||
- Embedding provider registry: `open-sse/config/embeddingRegistry.ts`
|
||||
- Image generation handler: `open-sse/handlers/imageGeneration.ts`
|
||||
- Image provider registry: `open-sse/config/imageRegistry.ts`
|
||||
|
||||
Services (business logic):
|
||||
|
||||
- Account selection/scoring: `open-sse/services/accountSelector.ts`
|
||||
- Context lifecycle management: `open-sse/services/contextManager.ts`
|
||||
- IP filter enforcement: `open-sse/services/ipFilter.ts`
|
||||
- Session tracking: `open-sse/services/sessionManager.ts`
|
||||
- Request deduplication: `open-sse/services/signatureCache.ts`
|
||||
- System prompt injection: `open-sse/services/systemPrompt.ts`
|
||||
- Thinking budget management: `open-sse/services/thinkingBudget.ts`
|
||||
- Wildcard model routing: `open-sse/services/wildcardRouter.ts`
|
||||
- Rate limit management: `open-sse/services/rateLimitManager.ts`
|
||||
- Circuit breaker: `open-sse/services/circuitBreaker.ts`
|
||||
|
||||
Domain layer modules:
|
||||
|
||||
- Model availability: `src/lib/domain/modelAvailability.ts`
|
||||
- Cost rules/budgets: `src/lib/domain/costRules.ts`
|
||||
- Fallback policy: `src/lib/domain/fallbackPolicy.ts`
|
||||
- Combo resolver: `src/lib/domain/comboResolver.ts`
|
||||
- Lockout policy: `src/lib/domain/lockoutPolicy.ts`
|
||||
- Policy engine: `src/domain/policyEngine.ts` — centralized lockout → budget → fallback evaluation
|
||||
- Error codes catalog: `src/lib/domain/errorCodes.ts`
|
||||
- Request ID: `src/lib/domain/requestId.ts`
|
||||
- Fetch timeout: `src/lib/domain/fetchTimeout.ts`
|
||||
- Request telemetry: `src/lib/domain/requestTelemetry.ts`
|
||||
- Compliance/audit: `src/lib/domain/compliance/index.ts`
|
||||
- Eval runner: `src/lib/domain/evalRunner.ts`
|
||||
- Domain state persistence: `src/lib/db/domainState.ts` — SQLite CRUD for fallback chains, budgets, cost history, lockout state, circuit breakers
|
||||
|
||||
OAuth provider modules (12 individual files under `src/lib/oauth/providers/`):
|
||||
|
||||
- Registry index: `src/lib/oauth/providers/index.ts`
|
||||
- Individual providers: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts`
|
||||
- Thin wrapper: `src/lib/oauth/providers.ts` — re-exports from individual modules
|
||||
|
||||
## 3) Persistence Layer
|
||||
|
||||
Primary state DB:
|
||||
|
||||
- `src/lib/localDb.ts`
|
||||
- file: `${DATA_DIR}/db.json` (or `$XDG_CONFIG_HOME/omniroute/db.json` when set, else `~/.omniroute/db.json`)
|
||||
- entities: providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt**
|
||||
|
||||
Usage DB:
|
||||
|
||||
- `src/lib/usageDb.ts`
|
||||
- files: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`
|
||||
- follows same base directory policy as `localDb` (`DATA_DIR`, then `XDG_CONFIG_HOME/omniroute` when set)
|
||||
- decomposed into focused sub-modules: `migrations.ts`, `usageHistory.ts`, `costCalculator.ts`, `usageStats.ts`, `callLogs.ts`
|
||||
|
||||
Domain State DB (SQLite):
|
||||
|
||||
- `src/lib/db/domainState.ts` — CRUD operations for domain state
|
||||
- Tables (created in `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers`
|
||||
- Write-through cache pattern: in-memory Maps are authoritative at runtime; mutations are written synchronously to SQLite; state is restored from DB on cold start
|
||||
|
||||
## 4) Auth + Security Surfaces
|
||||
|
||||
- Dashboard cookie auth: `src/proxy.ts`, `src/app/api/auth/login/route.ts`
|
||||
- API key generation/verification: `src/shared/utils/apiKey.ts`
|
||||
- Provider secrets persisted in `providerConnections` entries
|
||||
- Outbound proxy support via `open-sse/utils/proxyFetch.ts` (env vars) and `open-sse/utils/networkProxy.ts` (configurable per-provider or global)
|
||||
|
||||
## 5) Cloud Sync
|
||||
|
||||
- Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts`
|
||||
- Periodic task: `src/shared/services/cloudSyncScheduler.ts`
|
||||
- Control route: `src/app/api/sync/cloud/route.ts`
|
||||
|
||||
## Request Lifecycle (`/v1/chat/completions`)
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
autonumber
|
||||
participant Client as CLI/SDK Client
|
||||
participant Route as /api/v1/chat/completions
|
||||
participant Chat as src/sse/handlers/chat
|
||||
participant Core as open-sse/handlers/chatCore
|
||||
participant Model as Model Resolver
|
||||
participant Auth as Credential Selector
|
||||
participant Exec as Provider Executor
|
||||
participant Prov as Upstream Provider
|
||||
participant Stream as Stream Translator
|
||||
participant Usage as usageDb
|
||||
|
||||
Client->>Route: POST /v1/chat/completions
|
||||
Route->>Chat: handleChat(request)
|
||||
Chat->>Model: parse/resolve model or combo
|
||||
|
||||
alt Combo model
|
||||
Chat->>Chat: iterate combo models (handleComboChat)
|
||||
end
|
||||
|
||||
Chat->>Auth: getProviderCredentials(provider)
|
||||
Auth-->>Chat: active account + tokens/api key
|
||||
|
||||
Chat->>Core: handleChatCore(body, modelInfo, credentials)
|
||||
Core->>Core: detect source format
|
||||
Core->>Core: translate request to target format
|
||||
Core->>Exec: execute(provider, transformedBody)
|
||||
Exec->>Prov: upstream API call
|
||||
Prov-->>Exec: SSE/JSON response
|
||||
Exec-->>Core: response + metadata
|
||||
|
||||
alt 401/403
|
||||
Core->>Exec: refreshCredentials()
|
||||
Exec-->>Core: updated tokens
|
||||
Core->>Exec: retry request
|
||||
end
|
||||
|
||||
Core->>Stream: translate/normalize stream to client format
|
||||
Stream-->>Client: SSE chunks / JSON response
|
||||
|
||||
Stream->>Usage: extract usage + persist history/log
|
||||
```
|
||||
|
||||
## Combo + Account Fallback Flow
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[Incoming model string] --> B{Is combo name?}
|
||||
B -- Yes --> C[Load combo models sequence]
|
||||
B -- No --> D[Single model path]
|
||||
|
||||
C --> E[Try model N]
|
||||
E --> F[Resolve provider/model]
|
||||
D --> F
|
||||
|
||||
F --> G[Select account credentials]
|
||||
G --> H{Credentials available?}
|
||||
H -- No --> I[Return provider unavailable]
|
||||
H -- Yes --> J[Execute request]
|
||||
|
||||
J --> K{Success?}
|
||||
K -- Yes --> L[Return response]
|
||||
K -- No --> M{Fallback-eligible error?}
|
||||
|
||||
M -- No --> N[Return error]
|
||||
M -- Yes --> O[Mark account unavailable cooldown]
|
||||
O --> P{Another account for provider?}
|
||||
P -- Yes --> G
|
||||
P -- No --> Q{In combo with next model?}
|
||||
Q -- Yes --> E
|
||||
Q -- No --> R[Return all unavailable]
|
||||
```
|
||||
|
||||
Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics.
|
||||
|
||||
## OAuth Onboarding and Token Refresh Lifecycle
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
autonumber
|
||||
participant UI as Dashboard UI
|
||||
participant OAuth as /api/oauth/[provider]/[action]
|
||||
participant ProvAuth as Provider Auth Server
|
||||
participant DB as localDb
|
||||
participant Test as /api/providers/[id]/test
|
||||
participant Exec as Provider Executor
|
||||
|
||||
UI->>OAuth: GET authorize or device-code
|
||||
OAuth->>ProvAuth: create auth/device flow
|
||||
ProvAuth-->>OAuth: auth URL or device code payload
|
||||
OAuth-->>UI: flow data
|
||||
|
||||
UI->>OAuth: POST exchange or poll
|
||||
OAuth->>ProvAuth: token exchange/poll
|
||||
ProvAuth-->>OAuth: access/refresh tokens
|
||||
OAuth->>DB: createProviderConnection(oauth data)
|
||||
OAuth-->>UI: success + connection id
|
||||
|
||||
UI->>Test: POST /api/providers/[id]/test
|
||||
Test->>Exec: validate credentials / optional refresh
|
||||
Exec-->>Test: valid or refreshed token info
|
||||
Test->>DB: update status/tokens/errors
|
||||
Test-->>UI: validation result
|
||||
```
|
||||
|
||||
Refresh during live traffic is executed inside `open-sse/handlers/chatCore.ts` via executor `refreshCredentials()`.
|
||||
|
||||
## Cloud Sync Lifecycle (Enable / Sync / Disable)
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
autonumber
|
||||
participant UI as Endpoint Page UI
|
||||
participant Sync as /api/sync/cloud
|
||||
participant DB as localDb
|
||||
participant Cloud as External Cloud Sync
|
||||
participant Claude as ~/.claude/settings.json
|
||||
|
||||
UI->>Sync: POST action=enable
|
||||
Sync->>DB: set cloudEnabled=true
|
||||
Sync->>DB: ensure API key exists
|
||||
Sync->>Cloud: POST /sync/{machineId} (providers/aliases/combos/keys)
|
||||
Cloud-->>Sync: sync result
|
||||
Sync->>Cloud: GET /{machineId}/v1/verify
|
||||
Sync-->>UI: enabled + verification status
|
||||
|
||||
UI->>Sync: POST action=sync
|
||||
Sync->>Cloud: POST /sync/{machineId}
|
||||
Cloud-->>Sync: remote data
|
||||
Sync->>DB: update newer local tokens/status
|
||||
Sync-->>UI: synced
|
||||
|
||||
UI->>Sync: POST action=disable
|
||||
Sync->>DB: set cloudEnabled=false
|
||||
Sync->>Cloud: DELETE /sync/{machineId}
|
||||
Sync->>Claude: switch ANTHROPIC_BASE_URL back to local (if needed)
|
||||
Sync-->>UI: disabled
|
||||
```
|
||||
|
||||
Periodic sync is triggered by `CloudSyncScheduler` when cloud is enabled.
|
||||
|
||||
## Data Model and Storage Map
|
||||
|
||||
```mermaid
|
||||
erDiagram
|
||||
SETTINGS ||--o{ PROVIDER_CONNECTION : controls
|
||||
PROVIDER_NODE ||--o{ PROVIDER_CONNECTION : backs_compatible_provider
|
||||
PROVIDER_CONNECTION ||--o{ USAGE_ENTRY : emits_usage
|
||||
|
||||
SETTINGS {
|
||||
boolean cloudEnabled
|
||||
number stickyRoundRobinLimit
|
||||
boolean requireLogin
|
||||
string password_hash
|
||||
string fallbackStrategy
|
||||
json rateLimitDefaults
|
||||
json providerProfiles
|
||||
}
|
||||
|
||||
PROVIDER_CONNECTION {
|
||||
string id
|
||||
string provider
|
||||
string authType
|
||||
string name
|
||||
number priority
|
||||
boolean isActive
|
||||
string apiKey
|
||||
string accessToken
|
||||
string refreshToken
|
||||
string expiresAt
|
||||
string testStatus
|
||||
string lastError
|
||||
string rateLimitedUntil
|
||||
json providerSpecificData
|
||||
}
|
||||
|
||||
PROVIDER_NODE {
|
||||
string id
|
||||
string type
|
||||
string name
|
||||
string prefix
|
||||
string apiType
|
||||
string baseUrl
|
||||
}
|
||||
|
||||
MODEL_ALIAS {
|
||||
string alias
|
||||
string targetModel
|
||||
}
|
||||
|
||||
COMBO {
|
||||
string id
|
||||
string name
|
||||
string[] models
|
||||
}
|
||||
|
||||
API_KEY {
|
||||
string id
|
||||
string name
|
||||
string key
|
||||
string machineId
|
||||
}
|
||||
|
||||
USAGE_ENTRY {
|
||||
string provider
|
||||
string model
|
||||
number prompt_tokens
|
||||
number completion_tokens
|
||||
string connectionId
|
||||
string timestamp
|
||||
}
|
||||
|
||||
CUSTOM_MODEL {
|
||||
string id
|
||||
string name
|
||||
string providerId
|
||||
}
|
||||
|
||||
PROXY_CONFIG {
|
||||
string global
|
||||
json providers
|
||||
}
|
||||
|
||||
IP_FILTER {
|
||||
string mode
|
||||
string[] allowlist
|
||||
string[] blocklist
|
||||
}
|
||||
|
||||
THINKING_BUDGET {
|
||||
string mode
|
||||
number customBudget
|
||||
string effortLevel
|
||||
}
|
||||
|
||||
SYSTEM_PROMPT {
|
||||
boolean enabled
|
||||
string prompt
|
||||
string position
|
||||
}
|
||||
```
|
||||
|
||||
Physical storage files:
|
||||
|
||||
- main state: `${DATA_DIR}/db.json` (or `$XDG_CONFIG_HOME/omniroute/db.json` when set, else `~/.omniroute/db.json`)
|
||||
- usage stats: `${DATA_DIR}/usage.json`
|
||||
- request log lines: `${DATA_DIR}/log.txt`
|
||||
- optional translator/request debug sessions: `<repo>/logs/...`
|
||||
|
||||
## Deployment Topology
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
subgraph LocalHost[Developer Host]
|
||||
CLI[CLI Tools]
|
||||
Browser[Dashboard Browser]
|
||||
end
|
||||
|
||||
subgraph ContainerOrProcess[OmniRoute Runtime]
|
||||
Next[Next.js Server\nPORT=20128]
|
||||
Core[SSE Core + Executors]
|
||||
MainDB[(db.json)]
|
||||
UsageDB[(usage.json/log.txt)]
|
||||
end
|
||||
|
||||
subgraph External[External Services]
|
||||
Providers[AI Providers]
|
||||
SyncCloud[Cloud Sync Service]
|
||||
end
|
||||
|
||||
CLI --> Next
|
||||
Browser --> Next
|
||||
Next --> Core
|
||||
Next --> MainDB
|
||||
Core --> MainDB
|
||||
Core --> UsageDB
|
||||
Core --> Providers
|
||||
Next --> SyncCloud
|
||||
```
|
||||
|
||||
## Module Mapping (Decision-Critical)
|
||||
|
||||
### Route and API Modules
|
||||
|
||||
- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs
|
||||
- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images)
|
||||
- `src/app/api/providers*`: provider CRUD, validation, testing
|
||||
- `src/app/api/provider-nodes*`: custom compatible node management
|
||||
- `src/app/api/provider-models`: custom model management (CRUD)
|
||||
- `src/app/api/models/catalog`: full model catalog API (all types grouped by provider)
|
||||
- `src/app/api/oauth/*`: OAuth/device-code flows
|
||||
- `src/app/api/keys*`: local API key lifecycle
|
||||
- `src/app/api/models/alias`: alias management
|
||||
- `src/app/api/combos*`: fallback combo management
|
||||
- `src/app/api/pricing`: pricing overrides for cost calculation
|
||||
- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE)
|
||||
- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST)
|
||||
- `src/app/api/usage/*`: usage and logs APIs
|
||||
- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers
|
||||
- `src/app/api/cli-tools/*`: local CLI config writers/checkers
|
||||
- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT)
|
||||
- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT)
|
||||
- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT)
|
||||
- `src/app/api/sessions`: active session listing (GET)
|
||||
- `src/app/api/rate-limits`: per-account rate limit status (GET)
|
||||
|
||||
### Routing and Execution Core
|
||||
|
||||
- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop
|
||||
- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup
|
||||
- `open-sse/executors/*`: provider-specific network and format behavior
|
||||
|
||||
### Translation Registry and Format Converters
|
||||
|
||||
- `open-sse/translator/index.ts`: translator registry and orchestration
|
||||
- Request translators: `open-sse/translator/request/*`
|
||||
- Response translators: `open-sse/translator/response/*`
|
||||
- Format constants: `open-sse/translator/formats.ts`
|
||||
|
||||
### Persistence
|
||||
|
||||
- `src/lib/localDb.ts`: persistent config/state
|
||||
- `src/lib/usageDb.ts`: usage history and rolling request logs
|
||||
|
||||
## Provider Executor Coverage (Strategy Pattern)
|
||||
|
||||
Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method.
|
||||
|
||||
| Executor | Provider(s) | Special Handling |
|
||||
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- |
|
||||
| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Dynamic URL/header config per provider |
|
||||
| `AntigravityExecutor` | Google Antigravity | Custom project/session IDs, Retry-After parsing |
|
||||
| `CodexExecutor` | OpenAI Codex | Injects system instructions, forces reasoning effort |
|
||||
| `CursorExecutor` | Cursor IDE | ConnectRPC protocol, Protobuf encoding, request signing via checksum |
|
||||
| `GithubExecutor` | GitHub Copilot | Copilot token refresh, VSCode-mimicking headers |
|
||||
| `KiroExecutor` | AWS CodeWhisperer/Kiro | AWS EventStream binary format → SSE conversion |
|
||||
| `GeminiCLIExecutor` | Gemini CLI | Google OAuth token refresh cycle |
|
||||
|
||||
All other providers (including custom compatible nodes) use the `DefaultExecutor`.
|
||||
|
||||
## Provider Compatibility Matrix
|
||||
|
||||
| Provider | Format | Auth | Stream | Non-Stream | Token Refresh | Usage API |
|
||||
| ---------------- | ---------------- | --------------------- | ---------------- | ---------- | ------------- | ------------------ |
|
||||
| Claude | claude | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Admin only |
|
||||
| Gemini | gemini | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console |
|
||||
| Gemini CLI | gemini-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console |
|
||||
| Antigravity | antigravity | OAuth | ✅ | ✅ | ✅ | ✅ Full quota API |
|
||||
| OpenAI | openai | API Key | ✅ | ✅ | ❌ | ❌ |
|
||||
| Codex | openai-responses | OAuth | ✅ forced | ❌ | ✅ | ✅ Rate limits |
|
||||
| GitHub Copilot | openai | OAuth + Copilot Token | ✅ | ✅ | ✅ | ✅ Quota snapshots |
|
||||
| Cursor | cursor | Custom checksum | ✅ | ✅ | ❌ | ❌ |
|
||||
| Kiro | kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Usage limits |
|
||||
| Qwen | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ Per request |
|
||||
| iFlow | openai | OAuth (Basic) | ✅ | ✅ | ✅ | ⚠️ Per request |
|
||||
| OpenRouter | openai | API Key | ✅ | ✅ | ❌ | ❌ |
|
||||
| GLM/Kimi/MiniMax | claude | API Key | ✅ | ✅ | ❌ | ❌ |
|
||||
| DeepSeek | openai | API Key | ✅ | ✅ | ❌ | ❌ |
|
||||
| Groq | openai | API Key | ✅ | ✅ | ❌ | ❌ |
|
||||
| xAI (Grok) | openai | API Key | ✅ | ✅ | ❌ | ❌ |
|
||||
| Mistral | openai | API Key | ✅ | ✅ | ❌ | ❌ |
|
||||
| Perplexity | openai | API Key | ✅ | ✅ | ❌ | ❌ |
|
||||
| Together AI | openai | API Key | ✅ | ✅ | ❌ | ❌ |
|
||||
| Fireworks AI | openai | API Key | ✅ | ✅ | ❌ | ❌ |
|
||||
| Cerebras | openai | API Key | ✅ | ✅ | ❌ | ❌ |
|
||||
| Cohere | openai | API Key | ✅ | ✅ | ❌ | ❌ |
|
||||
| NVIDIA NIM | openai | API Key | ✅ | ✅ | ❌ | ❌ |
|
||||
|
||||
## Format Translation Coverage
|
||||
|
||||
Detected source formats include:
|
||||
|
||||
- `openai`
|
||||
- `openai-responses`
|
||||
- `claude`
|
||||
- `gemini`
|
||||
|
||||
Target formats include:
|
||||
|
||||
- OpenAI chat/Responses
|
||||
- Claude
|
||||
- Gemini/Gemini-CLI/Antigravity envelope
|
||||
- Kiro
|
||||
- Cursor
|
||||
|
||||
Translations use **OpenAI as the hub format** — all conversions go through OpenAI as intermediate:
|
||||
|
||||
```
|
||||
Source Format → OpenAI (hub) → Target Format
|
||||
```
|
||||
|
||||
Translations are selected dynamically based on source payload shape and provider target format.
|
||||
|
||||
## Supported API Endpoints
|
||||
|
||||
| Endpoint | Format | Handler |
|
||||
| -------------------------------------------------- | ------------------ | ---------------------------------------------------- |
|
||||
| `POST /v1/chat/completions` | OpenAI Chat | `src/sse/handlers/chat.ts` |
|
||||
| `POST /v1/messages` | Claude Messages | Same handler (auto-detected) |
|
||||
| `POST /v1/responses` | OpenAI Responses | `open-sse/handlers/responsesHandler.ts` |
|
||||
| `POST /v1/embeddings` | OpenAI Embeddings | `open-sse/handlers/embeddings.ts` |
|
||||
| `GET /v1/embeddings` | Model listing | API route |
|
||||
| `POST /v1/images/generations` | OpenAI Images | `open-sse/handlers/imageGeneration.ts` |
|
||||
| `GET /v1/images/generations` | Model listing | API route |
|
||||
| `POST /v1/providers/{provider}/chat/completions` | OpenAI Chat | Dedicated per-provider with model validation |
|
||||
| `POST /v1/providers/{provider}/embeddings` | OpenAI Embeddings | Dedicated per-provider with model validation |
|
||||
| `POST /v1/providers/{provider}/images/generations` | OpenAI Images | Dedicated per-provider with model validation |
|
||||
| `POST /v1/messages/count_tokens` | Claude Token Count | API route |
|
||||
| `GET /v1/models` | OpenAI Models list | API route (chat + embedding + image + custom models) |
|
||||
| `GET /api/models/catalog` | Catalog | All models grouped by provider + type |
|
||||
| `POST /v1beta/models/*:streamGenerateContent` | Gemini native | API route |
|
||||
| `GET/PUT/DELETE /api/settings/proxy` | Proxy Config | Network proxy configuration |
|
||||
| `POST /api/settings/proxy/test` | Proxy Connectivity | Proxy health/connectivity test endpoint |
|
||||
| `GET/POST/DELETE /api/provider-models` | Custom Models | Custom model management per provider |
|
||||
|
||||
## Bypass Handler
|
||||
|
||||
The bypass handler (`open-sse/utils/bypassHandler.ts`) intercepts known "throwaway" requests from Claude CLI — warmup pings, title extractions, and token counts — and returns a **fake response** without consuming upstream provider tokens. This is triggered only when `User-Agent` contains `claude-cli`.
|
||||
|
||||
## Request Logger Pipeline
|
||||
|
||||
The request logger (`open-sse/utils/requestLogger.ts`) provides a 7-stage debug logging pipeline, disabled by default, enabled via `ENABLE_REQUEST_LOGS=true`:
|
||||
|
||||
```
|
||||
1_req_client.json → 2_req_source.json → 3_req_openai.json → 4_req_target.json
|
||||
→ 5_res_provider.txt → 6_res_openai.txt → 7_res_client.txt
|
||||
```
|
||||
|
||||
Files are written to `<repo>/logs/<session>/` for each request session.
|
||||
|
||||
## Failure Modes and Resilience
|
||||
|
||||
## 1) Account/Provider Availability
|
||||
|
||||
- provider account cooldown on transient/rate/auth errors
|
||||
- account fallback before failing request
|
||||
- combo model fallback when current model/provider path is exhausted
|
||||
|
||||
## 2) Token Expiry
|
||||
|
||||
- pre-check and refresh with retry for refreshable providers
|
||||
- 401/403 retry after refresh attempt in core path
|
||||
|
||||
## 3) Stream Safety
|
||||
|
||||
- disconnect-aware stream controller
|
||||
- translation stream with end-of-stream flush and `[DONE]` handling
|
||||
- usage estimation fallback when provider usage metadata is missing
|
||||
|
||||
## 4) Cloud Sync Degradation
|
||||
|
||||
- sync errors are surfaced but local runtime continues
|
||||
- scheduler has retry-capable logic, but periodic execution currently calls single-attempt sync by default
|
||||
|
||||
## 5) Data Integrity
|
||||
|
||||
- DB shape migration/repair for missing keys
|
||||
- corrupt JSON reset safeguards for localDb and usageDb
|
||||
|
||||
## Observability and Operational Signals
|
||||
|
||||
Runtime visibility sources:
|
||||
|
||||
- console logs from `src/sse/utils/logger.ts`
|
||||
- per-request usage aggregates in `usage.json`
|
||||
- textual request status log in `log.txt`
|
||||
- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true`
|
||||
- dashboard usage endpoints (`/api/usage/*`) for UI consumption
|
||||
|
||||
## Security-Sensitive Boundaries
|
||||
|
||||
- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing
|
||||
- Initial password fallback (`INITIAL_PASSWORD`, default `123456`) must be overridden in real deployments
|
||||
- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format
|
||||
- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level
|
||||
- Cloud sync endpoints rely on API key auth + machine id semantics
|
||||
|
||||
## Environment and Runtime Matrix
|
||||
|
||||
Environment variables actively used by code:
|
||||
|
||||
- App/auth: `JWT_SECRET`, `INITIAL_PASSWORD`
|
||||
- Storage: `DATA_DIR`
|
||||
- Compatible node behavior: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE`
|
||||
- Optional storage base override (Linux/macOS when `DATA_DIR` unset): `XDG_CONFIG_HOME`
|
||||
- Security hashing: `API_KEY_SECRET`, `MACHINE_ID_SALT`
|
||||
- Logging: `ENABLE_REQUEST_LOGS`
|
||||
- Sync/cloud URLing: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL`
|
||||
- Outbound proxy: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` and lowercase variants
|
||||
- SOCKS5 feature flags: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY`
|
||||
- Platform/runtime helpers (not app-specific config): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME`
|
||||
|
||||
## Known Architectural Notes
|
||||
|
||||
1. `usageDb` and `localDb` now share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration.
|
||||
2. `/api/v1/route.ts` returns a static model list and is not the main models source used by `/v1/models`.
|
||||
3. Request logger writes full headers/body when enabled; treat log directory as sensitive.
|
||||
4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability.
|
||||
5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency.
|
||||
6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates).
|
||||
7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:plan3`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`).
|
||||
8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy).
|
||||
|
||||
## Operational Verification Checklist
|
||||
|
||||
- Build from source: `cd /root/dev/omniroute && npm run build`
|
||||
- Build Docker image: `cd /root/dev/omniroute && docker build -t omniroute .`
|
||||
- Start service and verify:
|
||||
- `GET /api/settings`
|
||||
- `GET /api/v1/models`
|
||||
- CLI target base URL should be `http://<host>:20128/v1` when `PORT=20128`
|
||||
587
docs/CODEBASE_DOCUMENTATION.md
Normal file
587
docs/CODEBASE_DOCUMENTATION.md
Normal file
@@ -0,0 +1,587 @@
|
||||
# omniroute — Codebase Documentation
|
||||
|
||||
> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router.
|
||||
|
||||
---
|
||||
|
||||
## 1. What Is omniroute?
|
||||
|
||||
omniroute is a **proxy router** that sits between AI clients (Claude CLI, Codex, Cursor IDE, etc.) and AI providers (Anthropic, Google, OpenAI, AWS, GitHub, etc.). It solves one big problem:
|
||||
|
||||
> **Different AI clients speak different "languages" (API formats), and different AI providers expect different "languages" too.** omniroute translates between them automatically.
|
||||
|
||||
Think of it like a universal translator at the United Nations — any delegate can speak any language, and the translator converts it for any other delegate.
|
||||
|
||||
---
|
||||
|
||||
## 2. Architecture Overview
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
subgraph Clients
|
||||
A[Claude CLI]
|
||||
B[Codex]
|
||||
C[Cursor IDE]
|
||||
D[OpenAI-compatible]
|
||||
end
|
||||
|
||||
subgraph omniroute
|
||||
E[Handler Layer]
|
||||
F[Translator Layer]
|
||||
G[Executor Layer]
|
||||
H[Services Layer]
|
||||
end
|
||||
|
||||
subgraph Providers
|
||||
I[Anthropic Claude]
|
||||
J[Google Gemini]
|
||||
K[OpenAI / Codex]
|
||||
L[GitHub Copilot]
|
||||
M[AWS Kiro]
|
||||
N[Antigravity]
|
||||
O[Cursor API]
|
||||
end
|
||||
|
||||
A --> E
|
||||
B --> E
|
||||
C --> E
|
||||
D --> E
|
||||
E --> F
|
||||
F --> G
|
||||
G --> I
|
||||
G --> J
|
||||
G --> K
|
||||
G --> L
|
||||
G --> M
|
||||
G --> N
|
||||
G --> O
|
||||
H -.-> E
|
||||
H -.-> G
|
||||
```
|
||||
|
||||
### Core Principle: Hub-and-Spoke Translation
|
||||
|
||||
All format translation passes through **OpenAI format as the hub**:
|
||||
|
||||
```
|
||||
Client Format → [OpenAI Hub] → Provider Format (request)
|
||||
Provider Format → [OpenAI Hub] → Client Format (response)
|
||||
```
|
||||
|
||||
This means you only need **N translators** (one per format) instead of **N²** (every pair).
|
||||
|
||||
---
|
||||
|
||||
## 3. Project Structure
|
||||
|
||||
```
|
||||
omniroute/
|
||||
├── open-sse/ ← Core proxy library (portable, framework-agnostic)
|
||||
│ ├── index.js ← Main entry point, exports everything
|
||||
│ ├── config/ ← Configuration & constants
|
||||
│ ├── executors/ ← Provider-specific request execution
|
||||
│ ├── handlers/ ← Request handling orchestration
|
||||
│ ├── services/ ← Business logic (auth, models, fallback, usage)
|
||||
│ ├── translator/ ← Format translation engine
|
||||
│ │ ├── request/ ← Request translators (8 files)
|
||||
│ │ ├── response/ ← Response translators (7 files)
|
||||
│ │ └── helpers/ ← Shared translation utilities (6 files)
|
||||
│ └── utils/ ← Utility functions
|
||||
├── src/ ← Application layer (Express/Worker runtime)
|
||||
│ ├── app/ ← Web UI, API routes, middleware
|
||||
│ ├── lib/ ← Database, auth, and shared library code
|
||||
│ ├── mitm/ ← Man-in-the-middle proxy utilities
|
||||
│ ├── models/ ← Database models
|
||||
│ ├── shared/ ← Shared utilities (wrappers around open-sse)
|
||||
│ ├── sse/ ← SSE endpoint handlers
|
||||
│ └── store/ ← State management
|
||||
├── data/ ← Runtime data (credentials, logs)
|
||||
│ └── provider-credentials.json (external credentials override, gitignored)
|
||||
└── tester/ ← Test utilities
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Module-by-Module Breakdown
|
||||
|
||||
### 4.1 Config (`open-sse/config/`)
|
||||
|
||||
The **single source of truth** for all provider configuration.
|
||||
|
||||
| File | Purpose |
|
||||
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `constants.ts` | `PROVIDERS` object with base URLs, OAuth credentials (defaults), headers, and default system prompts for every provider. Also defines `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG`, and `SKIP_PATTERNS`. |
|
||||
| `credentialLoader.ts` | Loads external credentials from `data/provider-credentials.json` and merges them over the hardcoded defaults in `PROVIDERS`. Keeps secrets out of source control while maintaining backwards compatibility. |
|
||||
| `providerModels.ts` | Central model registry: maps provider aliases → model IDs. Functions like `getModels()`, `getProviderByAlias()`. |
|
||||
| `codexInstructions.ts` | System instructions injected into Codex requests (editing constraints, sandbox rules, approval policies). |
|
||||
| `defaultThinkingSignature.ts` | Default "thinking" signatures for Claude and Gemini models. |
|
||||
| `ollamaModels.ts` | Schema definition for local Ollama models (name, size, family, quantization). |
|
||||
|
||||
#### Credential Loading Flow
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A["App starts"] --> B["constants.ts defines PROVIDERS\nwith hardcoded defaults"]
|
||||
B --> C{"data/provider-credentials.json\nexists?"}
|
||||
C -->|Yes| D["credentialLoader reads JSON"]
|
||||
C -->|No| E["Use hardcoded defaults"]
|
||||
D --> F{"For each provider in JSON"}
|
||||
F --> G{"Provider exists\nin PROVIDERS?"}
|
||||
G -->|No| H["Log warning, skip"]
|
||||
G -->|Yes| I{"Value is object?"}
|
||||
I -->|No| J["Log warning, skip"]
|
||||
I -->|Yes| K["Merge clientId, clientSecret,\ntokenUrl, authUrl, refreshUrl"]
|
||||
K --> F
|
||||
H --> F
|
||||
J --> F
|
||||
F -->|Done| L["PROVIDERS ready with\nmerged credentials"]
|
||||
E --> L
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4.2 Executors (`open-sse/executors/`)
|
||||
|
||||
Executors encapsulate **provider-specific logic** using the **Strategy Pattern**. Each executor overrides base methods as needed.
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class BaseExecutor {
|
||||
+buildUrl(model, stream, options)
|
||||
+buildHeaders(credentials, stream, body)
|
||||
+transformRequest(body, model, stream, credentials)
|
||||
+execute(url, options)
|
||||
+shouldRetry(status, error)
|
||||
+refreshCredentials(credentials, log)
|
||||
}
|
||||
|
||||
class DefaultExecutor {
|
||||
+refreshCredentials()
|
||||
}
|
||||
|
||||
class AntigravityExecutor {
|
||||
+buildUrl()
|
||||
+buildHeaders()
|
||||
+transformRequest()
|
||||
+shouldRetry()
|
||||
+refreshCredentials()
|
||||
}
|
||||
|
||||
class CursorExecutor {
|
||||
+buildUrl()
|
||||
+buildHeaders()
|
||||
+transformRequest()
|
||||
+parseResponse()
|
||||
+generateChecksum()
|
||||
}
|
||||
|
||||
class KiroExecutor {
|
||||
+buildUrl()
|
||||
+buildHeaders()
|
||||
+transformRequest()
|
||||
+parseEventStream()
|
||||
+refreshCredentials()
|
||||
}
|
||||
|
||||
BaseExecutor <|-- DefaultExecutor
|
||||
BaseExecutor <|-- AntigravityExecutor
|
||||
BaseExecutor <|-- CursorExecutor
|
||||
BaseExecutor <|-- KiroExecutor
|
||||
BaseExecutor <|-- CodexExecutor
|
||||
BaseExecutor <|-- GeminiCLIExecutor
|
||||
BaseExecutor <|-- GithubExecutor
|
||||
```
|
||||
|
||||
| Executor | Provider | Key Specializations |
|
||||
| ---------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
|
||||
| `base.ts` | — | Abstract base: URL building, headers, retry logic, credential refresh |
|
||||
| `default.ts` | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Generic OAuth token refresh for standard providers |
|
||||
| `antigravity.ts` | Google Cloud Code | Project/session ID generation, multi-URL fallback, custom retry parsing from error messages ("reset after 2h7m23s") |
|
||||
| `cursor.ts` | Cursor IDE | **Most complex**: SHA-256 checksum auth, Protobuf request encoding, binary EventStream → SSE response parsing |
|
||||
| `codex.ts` | OpenAI Codex | Injects system instructions, manages thinking levels, removes unsupported parameters |
|
||||
| `gemini-cli.ts` | Google Gemini CLI | Custom URL building (`streamGenerateContent`), Google OAuth token refresh |
|
||||
| `github.ts` | GitHub Copilot | Dual token system (GitHub OAuth + Copilot token), VSCode header mimicking |
|
||||
| `kiro.ts` | AWS CodeWhisperer | AWS EventStream binary parsing, AMZN event frames, token estimation |
|
||||
| `index.ts` | — | Factory: maps provider name → executor class, with default fallback |
|
||||
|
||||
---
|
||||
|
||||
### 4.3 Handlers (`open-sse/handlers/`)
|
||||
|
||||
The **orchestration layer** — coordinates translation, execution, streaming, and error handling.
|
||||
|
||||
| File | Purpose |
|
||||
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `chatCore.ts` | **Central orchestrator** (~600 lines). Handles the complete request lifecycle: format detection → translation → executor dispatch → streaming/non-streaming response → token refresh → error handling → usage logging. |
|
||||
| `responsesHandler.ts` | Adapter for OpenAI's Responses API: converts Responses format → Chat Completions → sends to `chatCore` → converts SSE back to Responses format. |
|
||||
| `embeddings.ts` | Embedding generation handler: resolves embedding model → provider, dispatches to provider API, returns OpenAI-compatible embedding response. Supports 6+ providers. |
|
||||
| `imageGeneration.ts` | Image generation handler: resolves image model → provider, supports OpenAI-compatible, Gemini-image (Antigravity), and fallback (Nebius) modes. Returns base64 or URL images. |
|
||||
|
||||
#### Request Lifecycle (chatCore.ts)
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client
|
||||
participant chatCore
|
||||
participant Translator
|
||||
participant Executor
|
||||
participant Provider
|
||||
|
||||
Client->>chatCore: Request (any format)
|
||||
chatCore->>chatCore: Detect source format
|
||||
chatCore->>chatCore: Check bypass patterns
|
||||
chatCore->>chatCore: Resolve model & provider
|
||||
chatCore->>Translator: Translate request (source → OpenAI → target)
|
||||
chatCore->>Executor: Get executor for provider
|
||||
Executor->>Executor: Build URL, headers, transform request
|
||||
Executor->>Executor: Refresh credentials if needed
|
||||
Executor->>Provider: HTTP fetch (streaming or non-streaming)
|
||||
|
||||
alt Streaming
|
||||
Provider-->>chatCore: SSE stream
|
||||
chatCore->>chatCore: Pipe through SSE transform stream
|
||||
Note over chatCore: Transform stream translates<br/>each chunk: target → OpenAI → source
|
||||
chatCore-->>Client: Translated SSE stream
|
||||
else Non-streaming
|
||||
Provider-->>chatCore: JSON response
|
||||
chatCore->>Translator: Translate response
|
||||
chatCore-->>Client: Translated JSON
|
||||
end
|
||||
|
||||
alt Error (401, 429, 500...)
|
||||
chatCore->>Executor: Retry with credential refresh
|
||||
chatCore->>chatCore: Account fallback logic
|
||||
end
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4.4 Services (`open-sse/services/`)
|
||||
|
||||
Business logic that supports the handlers and executors.
|
||||
|
||||
| File | Purpose |
|
||||
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `provider.ts` | **Format detection** (`detectFormat`): analyzes request body structure to identify Claude/OpenAI/Gemini/Antigravity/Responses formats (includes `max_tokens` heuristic for Claude). Also: URL building, header building, thinking config normalization. Supports `openai-compatible-*` and `anthropic-compatible-*` dynamic providers. |
|
||||
| `model.ts` | Model string parsing (`claude/model-name` → `{provider: "claude", model: "model-name"}`), alias resolution with collision detection, input sanitization (rejects path traversal/control chars), and model info resolution with async alias getter support. |
|
||||
| `accountFallback.ts` | Rate-limit handling: exponential backoff (1s → 2s → 4s → max 2min), account cooldown management, error classification (which errors trigger fallback vs. not). |
|
||||
| `tokenRefresh.ts` | OAuth token refresh for **every provider**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). Includes in-flight promise deduplication cache and retry with exponential backoff. |
|
||||
| `combo.ts` | **Combo models**: chains of fallback models. If model A fails with a fallback-eligible error, try model B, then C, etc. Returns actual upstream status codes. |
|
||||
| `usage.ts` | Fetches quota/usage data from provider APIs (GitHub Copilot quotas, Antigravity model quotas, Codex rate limits, Kiro usage breakdowns, Claude settings). |
|
||||
| `accountSelector.ts` | Smart account selection with scoring algorithm: considers priority, health status, round-robin position, and cooldown state to pick the optimal account for each request. |
|
||||
| `contextManager.ts` | Request context lifecycle management: creates and tracks per-request context objects with metadata (request ID, timestamps, provider info) for debugging and logging. |
|
||||
| `ipFilter.ts` | IP-based access control: supports allowlist and blocklist modes. Validates client IP against configured rules before processing API requests. |
|
||||
| `sessionManager.ts` | Session tracking with client fingerprinting: tracks active sessions using hashed client identifiers, monitors request counts, and provides session metrics. |
|
||||
| `signatureCache.ts` | Request signature-based deduplication cache: prevents duplicate requests by caching recent request signatures and returning cached responses for identical requests within a time window. |
|
||||
| `systemPrompt.ts` | Global system prompt injection: prepends or appends a configurable system prompt to all requests, with per-provider compatibility handling. |
|
||||
| `thinkingBudget.ts` | Reasoning token budget management: supports passthrough, auto (strip thinking config), custom (fixed budget), and adaptive (complexity-scaled) modes for controlling thinking/reasoning tokens. |
|
||||
| `wildcardRouter.ts` | Wildcard model pattern routing: resolves wildcard patterns (e.g., `*/claude-*`) to concrete provider/model pairs based on availability and priority. |
|
||||
|
||||
#### Token Refresh Deduplication
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant R1 as Request 1
|
||||
participant R2 as Request 2
|
||||
participant Cache as refreshPromiseCache
|
||||
participant OAuth as OAuth Provider
|
||||
|
||||
R1->>Cache: getAccessToken("gemini", token)
|
||||
Cache->>Cache: No in-flight promise
|
||||
Cache->>OAuth: Start refresh
|
||||
R2->>Cache: getAccessToken("gemini", token)
|
||||
Cache->>Cache: Found in-flight promise
|
||||
Cache-->>R2: Return existing promise
|
||||
OAuth-->>Cache: New access token
|
||||
Cache-->>R1: New access token
|
||||
Cache-->>R2: Same access token (shared)
|
||||
Cache->>Cache: Delete cache entry
|
||||
```
|
||||
|
||||
#### Account Fallback State Machine
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> Active
|
||||
Active --> Error: Request fails (401/429/500)
|
||||
Error --> Cooldown: Apply backoff
|
||||
Cooldown --> Active: Cooldown expires
|
||||
Active --> Active: Request succeeds (reset backoff)
|
||||
|
||||
state Error {
|
||||
[*] --> ClassifyError
|
||||
ClassifyError --> ShouldFallback: Rate limit / Auth / Transient
|
||||
ClassifyError --> NoFallback: 400 Bad Request
|
||||
}
|
||||
|
||||
state Cooldown {
|
||||
[*] --> ExponentialBackoff
|
||||
ExponentialBackoff: Level 0 = 1s
|
||||
ExponentialBackoff: Level 1 = 2s
|
||||
ExponentialBackoff: Level 2 = 4s
|
||||
ExponentialBackoff: Max = 2min
|
||||
}
|
||||
```
|
||||
|
||||
#### Combo Model Chain
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A["Request with\ncombo model"] --> B["Model A"]
|
||||
B -->|"2xx Success"| C["Return response"]
|
||||
B -->|"429/401/500"| D{"Fallback\neligible?"}
|
||||
D -->|Yes| E["Model B"]
|
||||
D -->|No| F["Return error"]
|
||||
E -->|"2xx Success"| C
|
||||
E -->|"429/401/500"| G{"Fallback\neligible?"}
|
||||
G -->|Yes| H["Model C"]
|
||||
G -->|No| F
|
||||
H -->|"2xx Success"| C
|
||||
H -->|"Fail"| I["All failed →\nReturn last status"]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4.5 Translator (`open-sse/translator/`)
|
||||
|
||||
The **format translation engine** using a self-registering plugin system.
|
||||
|
||||
#### Architecture
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
subgraph "Request Translation"
|
||||
A["Claude → OpenAI"]
|
||||
B["Gemini → OpenAI"]
|
||||
C["Antigravity → OpenAI"]
|
||||
D["OpenAI Responses → OpenAI"]
|
||||
E["OpenAI → Claude"]
|
||||
F["OpenAI → Gemini"]
|
||||
G["OpenAI → Kiro"]
|
||||
H["OpenAI → Cursor"]
|
||||
end
|
||||
|
||||
subgraph "Response Translation"
|
||||
I["Claude → OpenAI"]
|
||||
J["Gemini → OpenAI"]
|
||||
K["Kiro → OpenAI"]
|
||||
L["Cursor → OpenAI"]
|
||||
M["OpenAI → Claude"]
|
||||
N["OpenAI → Antigravity"]
|
||||
O["OpenAI → Responses"]
|
||||
end
|
||||
```
|
||||
|
||||
| Directory | Files | Description |
|
||||
| ------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `request/` | 8 translators | Convert request bodies between formats. Each file self-registers via `register(from, to, fn)` on import. |
|
||||
| `response/` | 7 translators | Convert streaming response chunks between formats. Handles SSE event types, thinking blocks, tool calls. |
|
||||
| `helpers/` | 6 helpers | Shared utilities: `claudeHelper` (system prompt extraction, thinking config), `geminiHelper` (parts/contents mapping), `openaiHelper` (format filtering), `toolCallHelper` (ID generation, missing response injection), `maxTokensHelper`, `responsesApiHelper`. |
|
||||
| `index.ts` | — | Translation engine: `translateRequest()`, `translateResponse()`, state management, registry. |
|
||||
| `formats.ts` | — | Format constants: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`. |
|
||||
|
||||
#### Key Design: Self-Registering Plugins
|
||||
|
||||
```javascript
|
||||
// Each translator file calls register() on import:
|
||||
import { register } from "../index.js";
|
||||
register("claude", "openai", translateClaudeToOpenAI);
|
||||
|
||||
// The index.js imports all translator files, triggering registration:
|
||||
import "./request/claude-to-openai.js"; // ← self-registers
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4.6 Utils (`open-sse/utils/`)
|
||||
|
||||
| File | Purpose |
|
||||
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `error.ts` | Error response building (OpenAI-compatible format), upstream error parsing, Antigravity retry-time extraction from error messages, SSE error streaming. |
|
||||
| `stream.ts` | **SSE Transform Stream** — the core streaming pipeline. Two modes: `TRANSLATE` (full format translation) and `PASSTHROUGH` (normalize + extract usage). Handles chunk buffering, usage estimation, content length tracking. Per-stream encoder/decoder instances avoid shared state. |
|
||||
| `streamHelpers.ts` | Low-level SSE utilities: `parseSSELine` (whitespace-tolerant), `hasValuableContent` (filters empty chunks for OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (format-aware SSE serialization with `perf_metrics` cleanup). |
|
||||
| `usageTracking.ts` | Token usage extraction from any format (Claude/OpenAI/Gemini/Responses), estimation with separate tool/message char-per-token ratios, buffer addition (2000 tokens safety margin), format-specific field filtering, console logging with ANSI colors. |
|
||||
| `requestLogger.ts` | File-based request logging (opt-in via `ENABLE_REQUEST_LOGS=true`). Creates session folders with numbered files: `1_req_client.json` → `7_res_client.txt`. All I/O is async (fire-and-forget). Masks sensitive headers. |
|
||||
| `bypassHandler.ts` | Intercepts specific patterns from Claude CLI (title extraction, warmup, count) and returns fake responses without calling any provider. Supports both streaming and non-streaming. Intentionally limited to Claude CLI scope. |
|
||||
| `networkProxy.ts` | Resolves outbound proxy URL for a given provider with precedence: provider-specific config → global config → environment variables (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Supports `NO_PROXY` exclusions. Caches config for 30s. |
|
||||
|
||||
#### SSE Streaming Pipeline
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A["Provider SSE stream"] --> B["TextDecoder\n(per-stream instance)"]
|
||||
B --> C["Buffer lines\n(split on newline)"]
|
||||
C --> D["parseSSELine()\n(trim whitespace, parse JSON)"]
|
||||
D --> E{"Mode?"}
|
||||
E -->|TRANSLATE| F["translateResponse()\ntarget → OpenAI → source"]
|
||||
E -->|PASSTHROUGH| G["fixInvalidId()\nnormalize chunk"]
|
||||
F --> H["hasValuableContent()\nfilter empty chunks"]
|
||||
G --> H
|
||||
H -->|"Has content"| I["extractUsage()\ntrack token counts"]
|
||||
H -->|"Empty"| J["Skip chunk"]
|
||||
I --> K["formatSSE()\nserialize + clean perf_metrics"]
|
||||
K --> L["TextEncoder\n(per-stream instance)"]
|
||||
L --> M["Enqueue to\nclient stream"]
|
||||
|
||||
style A fill:#f9f,stroke:#333
|
||||
style M fill:#9f9,stroke:#333
|
||||
```
|
||||
|
||||
#### Request Logger Session Structure
|
||||
|
||||
```
|
||||
logs/
|
||||
└── claude_gemini_claude-sonnet_20260208_143045/
|
||||
├── 1_req_client.json ← Raw client request
|
||||
├── 2_req_source.json ← After initial conversion
|
||||
├── 3_req_openai.json ← OpenAI intermediate format
|
||||
├── 4_req_target.json ← Final target format
|
||||
├── 5_res_provider.txt ← Provider SSE chunks (streaming)
|
||||
├── 5_res_provider.json ← Provider response (non-streaming)
|
||||
├── 6_res_openai.txt ← OpenAI intermediate chunks
|
||||
├── 7_res_client.txt ← Client-facing SSE chunks
|
||||
└── 6_error.json ← Error details (if any)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4.7 Application Layer (`src/`)
|
||||
|
||||
| Directory | Purpose |
|
||||
| ------------- | ---------------------------------------------------------------------- |
|
||||
| `src/app/` | Web UI, API routes, Express middleware, OAuth callback handlers |
|
||||
| `src/lib/` | Database access (`localDb.ts`, `usageDb.ts`), authentication, shared |
|
||||
| `src/mitm/` | Man-in-the-middle proxy utilities for intercepting provider traffic |
|
||||
| `src/models/` | Database model definitions |
|
||||
| `src/shared/` | Wrappers around open-sse functions (provider, stream, error, etc.) |
|
||||
| `src/sse/` | SSE endpoint handlers that wire the open-sse library to Express routes |
|
||||
| `src/store/` | Application state management |
|
||||
|
||||
#### Notable API Routes
|
||||
|
||||
| Route | Methods | Purpose |
|
||||
| --------------------------------------------- | --------------- | ------------------------------------------------------------------------------------- |
|
||||
| `/api/provider-models` | GET/POST/DELETE | CRUD for custom models per provider |
|
||||
| `/api/models/catalog` | GET | Aggregated catalog of all models (chat, embedding, image, custom) grouped by provider |
|
||||
| `/api/settings/proxy` | GET/PUT/DELETE | Hierarchical outbound proxy configuration (`global/providers/combos/keys`) |
|
||||
| `/api/settings/proxy/test` | POST | Validates proxy connectivity and returns public IP/latency |
|
||||
| `/v1/providers/[provider]/chat/completions` | POST | Dedicated per-provider chat completions with model validation |
|
||||
| `/v1/providers/[provider]/embeddings` | POST | Dedicated per-provider embeddings with model validation |
|
||||
| `/v1/providers/[provider]/images/generations` | POST | Dedicated per-provider image generation with model validation |
|
||||
| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist management |
|
||||
| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget configuration (passthrough/auto/custom/adaptive) |
|
||||
| `/api/settings/system-prompt` | GET/PUT | Global system prompt injection for all requests |
|
||||
| `/api/sessions` | GET | Active session tracking and metrics |
|
||||
| `/api/rate-limits` | GET | Per-account rate limit status |
|
||||
|
||||
---
|
||||
|
||||
## 5. Key Design Patterns
|
||||
|
||||
### 5.1 Hub-and-Spoke Translation
|
||||
|
||||
All formats translate through **OpenAI format as the hub**. Adding a new provider only requires writing **one pair** of translators (to/from OpenAI), not N pairs.
|
||||
|
||||
### 5.2 Executor Strategy Pattern
|
||||
|
||||
Each provider has a dedicated executor class inheriting from `BaseExecutor`. The factory in `executors/index.ts` selects the right one at runtime.
|
||||
|
||||
### 5.3 Self-Registering Plugin System
|
||||
|
||||
Translator modules register themselves on import via `register()`. Adding a new translator is just creating a file and importing it.
|
||||
|
||||
### 5.4 Account Fallback with Exponential Backoff
|
||||
|
||||
When a provider returns 429/401/500, the system can switch to the next account, applying exponential cooldowns (1s → 2s → 4s → max 2min).
|
||||
|
||||
### 5.5 Combo Model Chains
|
||||
|
||||
A "combo" groups multiple `provider/model` strings. If the first fails, fallback to the next automatically.
|
||||
|
||||
### 5.6 Stateful Streaming Translation
|
||||
|
||||
Response translation maintains state across SSE chunks (thinking block tracking, tool call accumulation, content block indexing) via the `initState()` mechanism.
|
||||
|
||||
### 5.7 Usage Safety Buffer
|
||||
|
||||
A 2000-token buffer is added to reported usage to prevent clients from hitting context window limits due to overhead from system prompts and format translation.
|
||||
|
||||
---
|
||||
|
||||
## 6. Supported Formats
|
||||
|
||||
| Format | Direction | Identifier |
|
||||
| ----------------------- | --------------- | ------------------ |
|
||||
| OpenAI Chat Completions | source + target | `openai` |
|
||||
| OpenAI Responses API | source + target | `openai-responses` |
|
||||
| Anthropic Claude | source + target | `claude` |
|
||||
| Google Gemini | source + target | `gemini` |
|
||||
| Google Gemini CLI | target only | `gemini-cli` |
|
||||
| Antigravity | source + target | `antigravity` |
|
||||
| AWS Kiro | target only | `kiro` |
|
||||
| Cursor | target only | `cursor` |
|
||||
|
||||
---
|
||||
|
||||
## 7. Supported Providers
|
||||
|
||||
| Provider | Auth Method | Executor | Key Notes |
|
||||
| ------------------------ | ---------------------- | ----------- | --------------------------------------------- |
|
||||
| Anthropic Claude | API key or OAuth | Default | Uses `x-api-key` header |
|
||||
| Google Gemini | API key or OAuth | Default | Uses `x-goog-api-key` header |
|
||||
| Google Gemini CLI | OAuth | GeminiCLI | Uses `streamGenerateContent` endpoint |
|
||||
| Antigravity | OAuth | Antigravity | Multi-URL fallback, custom retry parsing |
|
||||
| OpenAI | API key | Default | Standard Bearer auth |
|
||||
| Codex | OAuth | Codex | Injects system instructions, manages thinking |
|
||||
| GitHub Copilot | OAuth + Copilot token | Github | Dual token, VSCode header mimicking |
|
||||
| Kiro (AWS) | AWS SSO OIDC or Social | Kiro | Binary EventStream parsing |
|
||||
| Cursor IDE | Checksum auth | Cursor | Protobuf encoding, SHA-256 checksums |
|
||||
| Qwen | OAuth | Default | Standard auth |
|
||||
| iFlow | OAuth (Basic + Bearer) | Default | Dual auth header |
|
||||
| OpenRouter | API key | Default | Standard Bearer auth |
|
||||
| GLM, Kimi, MiniMax | API key | Default | Claude-compatible, use `x-api-key` |
|
||||
| `openai-compatible-*` | API key | Default | Dynamic: any OpenAI-compatible endpoint |
|
||||
| `anthropic-compatible-*` | API key | Default | Dynamic: any Claude-compatible endpoint |
|
||||
|
||||
---
|
||||
|
||||
## 8. Data Flow Summary
|
||||
|
||||
### Streaming Request
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A["Client"] --> B["detectFormat()"]
|
||||
B --> C["translateRequest()\nsource → OpenAI → target"]
|
||||
C --> D["Executor\nbuildUrl + buildHeaders"]
|
||||
D --> E["fetch(providerURL)"]
|
||||
E --> F["createSSEStream()\nTRANSLATE mode"]
|
||||
F --> G["parseSSELine()"]
|
||||
G --> H["translateResponse()\ntarget → OpenAI → source"]
|
||||
H --> I["extractUsage()\n+ addBuffer"]
|
||||
I --> J["formatSSE()"]
|
||||
J --> K["Client receives\ntranslated SSE"]
|
||||
K --> L["logUsage()\nsaveRequestUsage()"]
|
||||
```
|
||||
|
||||
### Non-Streaming Request
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A["Client"] --> B["detectFormat()"]
|
||||
B --> C["translateRequest()\nsource → OpenAI → target"]
|
||||
C --> D["Executor.execute()"]
|
||||
D --> E["translateResponse()\ntarget → OpenAI → source"]
|
||||
E --> F["Return JSON\nresponse"]
|
||||
```
|
||||
|
||||
### Bypass Flow (Claude CLI)
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A["Claude CLI request"] --> B{"Match bypass\npattern?"}
|
||||
B -->|"Title/Warmup/Count"| C["Generate fake\nOpenAI response"]
|
||||
B -->|"No match"| D["Normal flow"]
|
||||
C --> E["Translate to\nsource format"]
|
||||
E --> F["Return without\ncalling provider"]
|
||||
```
|
||||
75
docs/FEATURES.md
Normal file
75
docs/FEATURES.md
Normal file
@@ -0,0 +1,75 @@
|
||||
# OmniRoute — Dashboard Features Gallery
|
||||
|
||||
Visual guide to every section of the OmniRoute dashboard.
|
||||
|
||||
---
|
||||
|
||||
## 🔌 Providers
|
||||
|
||||
Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro).
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🎨 Combos
|
||||
|
||||
Create model routing combos with 6 strategies: fill-first, round-robin, power-of-two-choices, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 📊 Analytics
|
||||
|
||||
Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🏥 System Health
|
||||
|
||||
Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Translator Playground
|
||||
|
||||
Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream).
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ Settings
|
||||
|
||||
General settings, system storage, backup management (export/import database), appearance (dark/light mode), security, routing, resilience, and advanced configuration.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🔧 CLI Tools
|
||||
|
||||
One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, and Antigravity.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 📝 Request Logs
|
||||
|
||||
Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🌐 API Endpoint
|
||||
|
||||
Your unified API endpoint with capability breakdown: Chat Completions, Embeddings, Image Generation, Reranking, Audio Transcription, and registered API keys.
|
||||
|
||||
|
||||
113
docs/TASKS.md
Normal file
113
docs/TASKS.md
Normal file
@@ -0,0 +1,113 @@
|
||||
# Rate Limiting & Flow Control Overhaul — Tasks
|
||||
|
||||
> Referência: [Relatório de Análise](../walkthrough.md) · Fase docs em `/docs/phases/`
|
||||
|
||||
---
|
||||
|
||||
## Fase 1 — Error Classification & Provider Profiles
|
||||
|
||||
### Backend Core
|
||||
|
||||
- [x] `constants.ts` — Substituir `COOLDOWN_MS.transient` por `transientInitial` (5s) + `transientMax` (60s)
|
||||
- [x] `constants.ts` — Adicionar `PROVIDER_PROFILES` (oauth / apikey) com cooldowns diferenciados
|
||||
- [x] `constants.ts` — Adicionar `DEFAULT_API_LIMITS` (100 RPM, 200ms minTime)
|
||||
- [x] `providerRegistry.ts` — Criar helper `getProviderCategory(providerId)` → `"oauth"` | `"apikey"`
|
||||
- [x] `accountFallback.ts` — Aceitar `provider` como parâmetro em `checkFallbackError`
|
||||
- [x] `accountFallback.ts` — Implementar backoff exponencial para 502/503/504 transientes
|
||||
- [x] `accountFallback.ts` — Calcular cooldown baseado no perfil do provedor
|
||||
- [x] `accountFallback.ts` — Adicionar helper `getProviderProfile(provider)`
|
||||
|
||||
### Callers (propagar `provider`)
|
||||
|
||||
- [x] `auth.ts` → `markAccountUnavailable` — Passar `provider` para `checkFallbackError`
|
||||
- [x] `combo.ts` → `handleComboChat` / `handleRoundRobinCombo` — Passar `provider` nos erros
|
||||
|
||||
### Testes
|
||||
|
||||
- [x] Atualizar `rate-limit-enhanced.test.mjs` — Teste "transient errors don't increase backoff" → `newBackoffLevel = 1`
|
||||
- [x] Criar `error-classification.test.mjs` — Cooldown exponencial 502, perfis OAuth/API, helper `getProviderCategory`
|
||||
|
||||
---
|
||||
|
||||
## Fase 2 — Circuit Breaker no Combo Pipeline
|
||||
|
||||
### Backend
|
||||
|
||||
- [x] `combo.ts` — Importar `getCircuitBreaker` e `CircuitBreakerOpenError`
|
||||
- [x] `combo.ts` — `handleComboChat` — Verificar `breaker.canExecute()` antes de cada modelo
|
||||
- [x] `combo.ts` — `handleRoundRobinCombo` — Integrar breaker per-model
|
||||
- [x] `combo.ts` — Marcar `semaphore.markRateLimited` para 502/503/504 (não só 429)
|
||||
- [x] `combo.ts` — Implementar early exit quando todos os modelos têm breaker OPEN
|
||||
|
||||
### Testes
|
||||
|
||||
- [x] Criar `combo-circuit-breaker.test.mjs` — Combo skip breaker OPEN, early exit, semáforo 502
|
||||
|
||||
---
|
||||
|
||||
## Fase 3 — Anti-Thundering Herd & Auto Rate Limit
|
||||
|
||||
### Backend
|
||||
|
||||
- [x] `rateLimitManager.ts` — Auto-enable para `apikey` providers com limites elevados
|
||||
- [x] `rateLimitManager.ts` — Criar limiter com defaults (100 RPM) quando não configurado
|
||||
- [x] `auth.ts` — Adicionar mutex na `markAccountUnavailable` para evitar marcação paralela
|
||||
|
||||
### Testes
|
||||
|
||||
- [x] Criar `thundering-herd.test.mjs` — Mutex, auto-enable, limites não restritivos
|
||||
|
||||
---
|
||||
|
||||
## Fase 4 — Frontend Resilience UI
|
||||
|
||||
### Settings Page
|
||||
|
||||
- [x] `settings/page.tsx` — Adicionar tab "Resilience" (icon: `health_and_safety`) entre Routing e Pricing
|
||||
|
||||
### Novos Componentes
|
||||
|
||||
- [x] Criar `ResilienceTab.tsx` — Layout com 4 cards (Provider Profiles → Rate Limiting → Circuit Breakers → Policies)
|
||||
- [x] Criar `ProviderProfilesCard.tsx` — Toggle OAuth/API Key, inputs para cooldowns
|
||||
- [x] Criar `CircuitBreakerCard.tsx` — Status real-time per-provider, auto-refresh 5s, botão reset
|
||||
- [x] Criar `RateLimitOverviewCard.tsx` — Tabela providers × accounts × cooldown — **agora editável com RPM, Min Gap, Max Concurrent**
|
||||
|
||||
### API Routes
|
||||
|
||||
- [x] Criar `api/resilience/route.ts` — GET (estado completo + defaults mesclados) + PATCH (salvar perfis + defaults)
|
||||
- [x] Criar `api/resilience/reset/route.ts` — POST (resetar breakers + cooldowns)
|
||||
|
||||
### Migração
|
||||
|
||||
- [x] `PoliciesPanel.tsx` movido de Security para Resilience tab
|
||||
|
||||
---
|
||||
|
||||
## Fase 5 — Settings Page Restructure (v0.9.0)
|
||||
|
||||
### Tab Reorganization
|
||||
|
||||
- [x] **Security** — Simplificado para Login/Password + IP Access Control
|
||||
- [x] **Routing** — Expandido para 6 estratégias globais com descrições
|
||||
- [x] **Resilience** — Reordenado: Provider Profiles → Rate Limiting (editável) → Circuit Breakers → Policies
|
||||
- [x] **AI** — Thinking Budget + System Prompt + Prompt Cache (movido do Advanced)
|
||||
- [x] **Advanced** — Simplificado para apenas Global Proxy
|
||||
|
||||
### Backend Routing Strategies
|
||||
|
||||
- [x] `auth.ts` — Implementar `random` (Fisher-Yates shuffle)
|
||||
- [x] `auth.ts` — Implementar `least-used` (sorted by lastUsedAt)
|
||||
- [x] `auth.ts` — Implementar `cost-optimized` (sorted by priority)
|
||||
- [x] `auth.ts` — Corrigir `p2c` (power-of-two-choices com health scoring)
|
||||
- [x] `settings.ts` — Expandir tipo `fallbackStrategy` para 6 valores
|
||||
|
||||
---
|
||||
|
||||
## Verificação Final
|
||||
|
||||
- [x] Rodar todos os testes unitários: `node --test tests/unit/*.test.mjs`
|
||||
- [x] Build do Next.js: `npm run build`
|
||||
- [x] Verificar aba Resilience no browser
|
||||
- [x] Testar persistência dos perfis (salvar → reload)
|
||||
- [x] Testar Reset All Breakers
|
||||
- [x] Verificar todas as 5 tabs reestruturadas
|
||||
211
docs/TROUBLESHOOTING.md
Normal file
211
docs/TROUBLESHOOTING.md
Normal file
@@ -0,0 +1,211 @@
|
||||
# Troubleshooting
|
||||
|
||||
Common problems and solutions for OmniRoute.
|
||||
|
||||
---
|
||||
|
||||
## Quick Fixes
|
||||
|
||||
| Problem | Solution |
|
||||
| ----------------------------- | ------------------------------------------------------------------ |
|
||||
| First login not working | Check `INITIAL_PASSWORD` in `.env` (default: `123456`) |
|
||||
| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` |
|
||||
| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` |
|
||||
|
||||
---
|
||||
|
||||
## Provider Issues
|
||||
|
||||
### "Language model did not provide messages"
|
||||
|
||||
**Cause:** Provider quota exhausted.
|
||||
|
||||
**Fix:**
|
||||
|
||||
1. Check dashboard quota tracker
|
||||
2. Use a combo with fallback tiers
|
||||
3. Switch to cheaper/free tier
|
||||
|
||||
### Rate Limiting
|
||||
|
||||
**Cause:** Subscription quota exhausted.
|
||||
|
||||
**Fix:**
|
||||
|
||||
- Add fallback: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`
|
||||
- Use GLM/MiniMax as cheap backup
|
||||
|
||||
### OAuth Token Expired
|
||||
|
||||
OmniRoute auto-refreshes tokens. If issues persist:
|
||||
|
||||
1. Dashboard → Provider → Reconnect
|
||||
2. Delete and re-add the provider connection
|
||||
|
||||
---
|
||||
|
||||
## Cloud Issues
|
||||
|
||||
### Cloud Sync Errors
|
||||
|
||||
1. Verify `BASE_URL` points to your running instance (e.g., `http://localhost:20128`)
|
||||
2. Verify `CLOUD_URL` points to your cloud endpoint (e.g., `https://omniroute.dev`)
|
||||
3. Keep `NEXT_PUBLIC_*` values aligned with server-side values
|
||||
|
||||
### Cloud `stream=false` Returns 500
|
||||
|
||||
**Symptom:** `Unexpected token 'd'...` on cloud endpoint for non-streaming calls.
|
||||
|
||||
**Cause:** Upstream returns SSE payload while client expects JSON.
|
||||
|
||||
**Workaround:** Use `stream=true` for cloud direct calls. Local runtime includes SSE→JSON fallback.
|
||||
|
||||
### Cloud Says Connected but "Invalid API key"
|
||||
|
||||
1. Create a fresh key from local dashboard (`/api/keys`)
|
||||
2. Run cloud sync: Enable Cloud → Sync Now
|
||||
3. Old/non-synced keys can still return `401` on cloud
|
||||
|
||||
---
|
||||
|
||||
## Docker Issues
|
||||
|
||||
### CLI Tool Shows Not Installed
|
||||
|
||||
1. Check runtime fields: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq`
|
||||
2. For portable mode: use image target `runner-cli` (bundled CLIs)
|
||||
3. For host mount mode: set `CLI_EXTRA_PATHS` and mount host bin directory as read-only
|
||||
4. If `installed=true` and `runnable=false`: binary was found but failed healthcheck
|
||||
|
||||
### Quick Runtime Validation
|
||||
|
||||
```bash
|
||||
curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
|
||||
curl -s http://localhost:20128/api/cli-tools/claude-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
|
||||
curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Cost Issues
|
||||
|
||||
### High Costs
|
||||
|
||||
1. Check usage stats in Dashboard → Usage
|
||||
2. Switch primary model to GLM/MiniMax
|
||||
3. Use free tier (Gemini CLI, iFlow) for non-critical tasks
|
||||
4. Set cost budgets per API key: Dashboard → API Keys → Budget
|
||||
|
||||
---
|
||||
|
||||
## Debugging
|
||||
|
||||
### Enable Request Logs
|
||||
|
||||
Set `ENABLE_REQUEST_LOGS=true` in your `.env` file. Logs appear under `logs/` directory.
|
||||
|
||||
### Check Provider Health
|
||||
|
||||
```bash
|
||||
# Health dashboard
|
||||
http://localhost:20128/dashboard/health
|
||||
|
||||
# API health check
|
||||
curl http://localhost:20128/api/monitoring/health
|
||||
```
|
||||
|
||||
### Runtime Storage
|
||||
|
||||
- Main state: `${DATA_DIR}/db.json` (providers, combos, aliases, keys, settings)
|
||||
- Usage: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`
|
||||
- Request logs: `<repo>/logs/...` (when `ENABLE_REQUEST_LOGS=true`)
|
||||
|
||||
---
|
||||
|
||||
## Circuit Breaker Issues
|
||||
|
||||
### Provider stuck in OPEN state
|
||||
|
||||
When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires.
|
||||
|
||||
**Fix:**
|
||||
|
||||
1. Go to **Dashboard → Settings → Resilience**
|
||||
2. Check the circuit breaker card for the affected provider
|
||||
3. Click **Reset All** to clear all breakers, or wait for the cooldown to expire
|
||||
4. Verify the provider is actually available before resetting
|
||||
|
||||
### Provider keeps tripping the circuit breaker
|
||||
|
||||
If a provider repeatedly enters OPEN state:
|
||||
|
||||
1. Check **Dashboard → Health → Provider Health** for the failure pattern
|
||||
2. Go to **Settings → Resilience → Provider Profiles** and increase the failure threshold
|
||||
3. Check if the provider has changed API limits or requires re-authentication
|
||||
4. Review latency telemetry — high latency may cause timeout-based failures
|
||||
|
||||
---
|
||||
|
||||
## Audio Transcription Issues
|
||||
|
||||
### "Unsupported model" error
|
||||
|
||||
- Ensure you're using the correct prefix: `deepgram/nova-3` or `assemblyai/best`
|
||||
- Verify the provider is connected in **Dashboard → Providers**
|
||||
|
||||
### Transcription returns empty or fails
|
||||
|
||||
- Check supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`
|
||||
- Verify file size is within provider limits (typically < 25MB)
|
||||
- Check provider API key validity in the provider card
|
||||
|
||||
---
|
||||
|
||||
## Translator Debugging
|
||||
|
||||
Use **Dashboard → Translator** to debug format translation issues:
|
||||
|
||||
| Mode | When to Use |
|
||||
| ---------------- | -------------------------------------------------------------------------------------------- |
|
||||
| **Playground** | Compare input/output formats side by side — paste a failing request to see how it translates |
|
||||
| **Chat Tester** | Send live messages and inspect the full request/response payload including headers |
|
||||
| **Test Bench** | Run batch tests across format combinations to find which translations are broken |
|
||||
| **Live Monitor** | Watch real-time request flow to catch intermittent translation issues |
|
||||
|
||||
### Common format issues
|
||||
|
||||
- **Thinking tags not appearing** — Check if the target provider supports thinking and the thinking budget setting
|
||||
- **Tool calls dropping** — Some format translations may strip unsupported fields; verify in Playground mode
|
||||
- **System prompt missing** — Claude and Gemini handle system prompts differently; check translation output
|
||||
|
||||
---
|
||||
|
||||
## Resilience Settings
|
||||
|
||||
### Auto rate-limit not triggering
|
||||
|
||||
- Auto rate-limit only applies to API key providers (not OAuth/subscription)
|
||||
- Verify **Settings → Resilience → Provider Profiles** has auto-rate-limit enabled
|
||||
- Check if the provider returns `429` status codes or `Retry-After` headers
|
||||
|
||||
### Tuning exponential backoff
|
||||
|
||||
Provider profiles support these settings:
|
||||
|
||||
- **Base delay** — Initial wait time after first failure (default: 1s)
|
||||
- **Max delay** — Maximum wait time cap (default: 30s)
|
||||
- **Multiplier** — How much to increase delay per consecutive failure (default: 2x)
|
||||
|
||||
### Anti-thundering herd
|
||||
|
||||
When many concurrent requests hit a rate-limited provider, OmniRoute uses mutex + auto rate-limiting to serialize requests and prevent cascading failures. This is automatic for API key providers.
|
||||
|
||||
---
|
||||
|
||||
## Still Stuck?
|
||||
|
||||
- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
|
||||
- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details
|
||||
- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints
|
||||
- **Health Dashboard**: Check **Dashboard → Health** for real-time system status
|
||||
- **Translator**: Use **Dashboard → Translator** to debug format issues
|
||||
696
docs/USER_GUIDE.md
Normal file
696
docs/USER_GUIDE.md
Normal file
@@ -0,0 +1,696 @@
|
||||
# User Guide
|
||||
|
||||
Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute.
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Pricing at a Glance](#-pricing-at-a-glance)
|
||||
- [Use Cases](#-use-cases)
|
||||
- [Provider Setup](#-provider-setup)
|
||||
- [CLI Integration](#-cli-integration)
|
||||
- [Deployment](#-deployment)
|
||||
- [Available Models](#-available-models)
|
||||
- [Advanced Features](#-advanced-features)
|
||||
|
||||
---
|
||||
|
||||
## 💰 Pricing at a Glance
|
||||
|
||||
| Tier | Provider | Cost | Quota Reset | Best For |
|
||||
| ------------------- | ----------------- | ----------- | ---------------- | -------------------- |
|
||||
| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |
|
||||
| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |
|
||||
| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |
|
||||
| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |
|
||||
| **🔑 API KEY** | DeepSeek | Pay per use | None | Cheap reasoning |
|
||||
| | Groq | Pay per use | None | Ultra-fast inference |
|
||||
| | xAI (Grok) | Pay per use | None | Grok 4 reasoning |
|
||||
| | Mistral | Pay per use | None | EU-hosted models |
|
||||
| | Perplexity | Pay per use | None | Search-augmented |
|
||||
| | Together AI | Pay per use | None | Open-source models |
|
||||
| | Fireworks AI | Pay per use | None | Fast FLUX images |
|
||||
| | Cerebras | Pay per use | None | Wafer-scale speed |
|
||||
| | Cohere | Pay per use | None | Command R+ RAG |
|
||||
| | NVIDIA NIM | Pay per use | None | Enterprise models |
|
||||
| **💰 CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |
|
||||
| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |
|
||||
| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |
|
||||
| **🆓 FREE** | iFlow | $0 | Unlimited | 8 models free |
|
||||
| | Qwen | $0 | Unlimited | 3 models free |
|
||||
| | Kiro | $0 | Unlimited | Claude free |
|
||||
|
||||
**💡 Pro Tip:** Start with Gemini CLI (180K free/month) + iFlow (unlimited free) combo = $0 cost!
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Use Cases
|
||||
|
||||
### Case 1: "I have Claude Pro subscription"
|
||||
|
||||
**Problem:** Quota expires unused, rate limits during heavy coding
|
||||
|
||||
```
|
||||
Combo: "maximize-claude"
|
||||
1. cc/claude-opus-4-6 (use subscription fully)
|
||||
2. glm/glm-4.7 (cheap backup when quota out)
|
||||
3. if/kimi-k2-thinking (free emergency fallback)
|
||||
|
||||
Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total
|
||||
vs. $20 + hitting limits = frustration
|
||||
```
|
||||
|
||||
### Case 2: "I want zero cost"
|
||||
|
||||
**Problem:** Can't afford subscriptions, need reliable AI coding
|
||||
|
||||
```
|
||||
Combo: "free-forever"
|
||||
1. gc/gemini-3-flash (180K free/month)
|
||||
2. if/kimi-k2-thinking (unlimited free)
|
||||
3. qw/qwen3-coder-plus (unlimited free)
|
||||
|
||||
Monthly cost: $0
|
||||
Quality: Production-ready models
|
||||
```
|
||||
|
||||
### Case 3: "I need 24/7 coding, no interruptions"
|
||||
|
||||
**Problem:** Deadlines, can't afford downtime
|
||||
|
||||
```
|
||||
Combo: "always-on"
|
||||
1. cc/claude-opus-4-6 (best quality)
|
||||
2. cx/gpt-5.2-codex (second subscription)
|
||||
3. glm/glm-4.7 (cheap, resets daily)
|
||||
4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
|
||||
5. if/kimi-k2-thinking (free unlimited)
|
||||
|
||||
Result: 5 layers of fallback = zero downtime
|
||||
Monthly cost: $20-200 (subscriptions) + $10-20 (backup)
|
||||
```
|
||||
|
||||
### Case 4: "I want FREE AI in OpenClaw"
|
||||
|
||||
**Problem:** Need AI assistant in messaging apps, completely free
|
||||
|
||||
```
|
||||
Combo: "openclaw-free"
|
||||
1. if/glm-4.7 (unlimited free)
|
||||
2. if/minimax-m2.1 (unlimited free)
|
||||
3. if/kimi-k2-thinking (unlimited free)
|
||||
|
||||
Monthly cost: $0
|
||||
Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📖 Provider Setup
|
||||
|
||||
### 🔐 Subscription Providers
|
||||
|
||||
#### Claude Code (Pro/Max)
|
||||
|
||||
```bash
|
||||
Dashboard → Providers → Connect Claude Code
|
||||
→ OAuth login → Auto token refresh
|
||||
→ 5-hour + weekly quota tracking
|
||||
|
||||
Models:
|
||||
cc/claude-opus-4-6
|
||||
cc/claude-sonnet-4-5-20250929
|
||||
cc/claude-haiku-4-5-20251001
|
||||
```
|
||||
|
||||
**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model!
|
||||
|
||||
#### OpenAI Codex (Plus/Pro)
|
||||
|
||||
```bash
|
||||
Dashboard → Providers → Connect Codex
|
||||
→ OAuth login (port 1455)
|
||||
→ 5-hour + weekly reset
|
||||
|
||||
Models:
|
||||
cx/gpt-5.2-codex
|
||||
cx/gpt-5.1-codex-max
|
||||
```
|
||||
|
||||
#### Gemini CLI (FREE 180K/month!)
|
||||
|
||||
```bash
|
||||
Dashboard → Providers → Connect Gemini CLI
|
||||
→ Google OAuth
|
||||
→ 180K completions/month + 1K/day
|
||||
|
||||
Models:
|
||||
gc/gemini-3-flash-preview
|
||||
gc/gemini-2.5-pro
|
||||
```
|
||||
|
||||
**Best Value:** Huge free tier! Use this before paid tiers.
|
||||
|
||||
#### GitHub Copilot
|
||||
|
||||
```bash
|
||||
Dashboard → Providers → Connect GitHub
|
||||
→ OAuth via GitHub
|
||||
→ Monthly reset (1st of month)
|
||||
|
||||
Models:
|
||||
gh/gpt-5
|
||||
gh/claude-4.5-sonnet
|
||||
gh/gemini-3-pro
|
||||
```
|
||||
|
||||
### 💰 Cheap Providers
|
||||
|
||||
#### GLM-4.7 (Daily reset, $0.6/1M)
|
||||
|
||||
1. Sign up: [Zhipu AI](https://open.bigmodel.cn/)
|
||||
2. Get API key from Coding Plan
|
||||
3. Dashboard → Add API Key: Provider: `glm`, API Key: `your-key`
|
||||
|
||||
**Use:** `glm/glm-4.7` — **Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.
|
||||
|
||||
#### MiniMax M2.1 (5h reset, $0.20/1M)
|
||||
|
||||
1. Sign up: [MiniMax](https://www.minimax.io/)
|
||||
2. Get API key → Dashboard → Add API Key
|
||||
|
||||
**Use:** `minimax/MiniMax-M2.1` — **Pro Tip:** Cheapest option for long context (1M tokens)!
|
||||
|
||||
#### Kimi K2 ($9/month flat)
|
||||
|
||||
1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/)
|
||||
2. Get API key → Dashboard → Add API Key
|
||||
|
||||
**Use:** `kimi/kimi-latest` — **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
|
||||
|
||||
### 🆓 FREE Providers
|
||||
|
||||
#### iFlow (8 FREE models)
|
||||
|
||||
```bash
|
||||
Dashboard → Connect iFlow → OAuth login → Unlimited usage
|
||||
|
||||
Models: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1
|
||||
```
|
||||
|
||||
#### Qwen (3 FREE models)
|
||||
|
||||
```bash
|
||||
Dashboard → Connect Qwen → Device code auth → Unlimited usage
|
||||
|
||||
Models: qw/qwen3-coder-plus, qw/qwen3-coder-flash
|
||||
```
|
||||
|
||||
#### Kiro (Claude FREE)
|
||||
|
||||
```bash
|
||||
Dashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited
|
||||
|
||||
Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎨 Combos
|
||||
|
||||
### Example 1: Maximize Subscription → Cheap Backup
|
||||
|
||||
```
|
||||
Dashboard → Combos → Create New
|
||||
|
||||
Name: premium-coding
|
||||
Models:
|
||||
1. cc/claude-opus-4-6 (Subscription primary)
|
||||
2. glm/glm-4.7 (Cheap backup, $0.6/1M)
|
||||
3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)
|
||||
|
||||
Use in CLI: premium-coding
|
||||
```
|
||||
|
||||
### Example 2: Free-Only (Zero Cost)
|
||||
|
||||
```
|
||||
Name: free-combo
|
||||
Models:
|
||||
1. gc/gemini-3-flash-preview (180K free/month)
|
||||
2. if/kimi-k2-thinking (unlimited)
|
||||
3. qw/qwen3-coder-plus (unlimited)
|
||||
|
||||
Cost: $0 forever!
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 CLI Integration
|
||||
|
||||
### Cursor IDE
|
||||
|
||||
```
|
||||
Settings → Models → Advanced:
|
||||
OpenAI API Base URL: http://localhost:20128/v1
|
||||
OpenAI API Key: [from omniroute dashboard]
|
||||
Model: cc/claude-opus-4-6
|
||||
```
|
||||
|
||||
### Claude Code
|
||||
|
||||
Edit `~/.claude/config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"anthropic_api_base": "http://localhost:20128/v1",
|
||||
"anthropic_api_key": "your-omniroute-api-key"
|
||||
}
|
||||
```
|
||||
|
||||
### Codex CLI
|
||||
|
||||
```bash
|
||||
export OPENAI_BASE_URL="http://localhost:20128"
|
||||
export OPENAI_API_KEY="your-omniroute-api-key"
|
||||
codex "your prompt"
|
||||
```
|
||||
|
||||
### OpenClaw
|
||||
|
||||
Edit `~/.openclaw/openclaw.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"agents": {
|
||||
"defaults": {
|
||||
"model": { "primary": "omniroute/if/glm-4.7" }
|
||||
}
|
||||
},
|
||||
"models": {
|
||||
"providers": {
|
||||
"omniroute": {
|
||||
"baseUrl": "http://localhost:20128/v1",
|
||||
"apiKey": "your-omniroute-api-key",
|
||||
"api": "openai-completions",
|
||||
"models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Or use Dashboard:** CLI Tools → OpenClaw → Auto-config
|
||||
|
||||
### Cline / Continue / RooCode
|
||||
|
||||
```
|
||||
Provider: OpenAI Compatible
|
||||
Base URL: http://localhost:20128/v1
|
||||
API Key: [from dashboard]
|
||||
Model: cc/claude-opus-4-6
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Deployment
|
||||
|
||||
### VPS Deployment
|
||||
|
||||
```bash
|
||||
git clone https://github.com/diegosouzapw/OmniRoute.git
|
||||
cd OmniRoute && npm install && npm run build
|
||||
|
||||
export JWT_SECRET="your-secure-secret-change-this"
|
||||
export INITIAL_PASSWORD="your-password"
|
||||
export DATA_DIR="/var/lib/omniroute"
|
||||
export PORT="20128"
|
||||
export HOSTNAME="0.0.0.0"
|
||||
export NODE_ENV="production"
|
||||
export NEXT_PUBLIC_BASE_URL="http://localhost:20128"
|
||||
export API_KEY_SECRET="endpoint-proxy-api-key-secret"
|
||||
|
||||
npm run start
|
||||
# Or: pm2 start npm --name omniroute -- start
|
||||
```
|
||||
|
||||
### Docker
|
||||
|
||||
```bash
|
||||
# Build image (default = runner-cli with codex/claude/droid preinstalled)
|
||||
docker build -t omniroute:cli .
|
||||
|
||||
# Portable mode (recommended)
|
||||
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli
|
||||
```
|
||||
|
||||
For host-integrated mode with CLI binaries, see the Docker section in the main docs.
|
||||
|
||||
### Environment Variables
|
||||
|
||||
| Variable | Default | Description |
|
||||
| --------------------- | ------------------------------------ | ------------------------------------------------------- |
|
||||
| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) |
|
||||
| `INITIAL_PASSWORD` | `123456` | First login password |
|
||||
| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) |
|
||||
| `PORT` | framework default | Service port (`20128` in examples) |
|
||||
| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) |
|
||||
| `NODE_ENV` | runtime default | Set `production` for deploy |
|
||||
| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL |
|
||||
| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL |
|
||||
| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys |
|
||||
| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` |
|
||||
| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs |
|
||||
| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) |
|
||||
|
||||
For the full environment variable reference, see the [README](../README.md).
|
||||
|
||||
---
|
||||
|
||||
## 📊 Available Models
|
||||
|
||||
<details>
|
||||
<summary><b>View all available models</b></summary>
|
||||
|
||||
**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
|
||||
|
||||
**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
|
||||
|
||||
**Gemini CLI (`gc/`)** — FREE: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
|
||||
|
||||
**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`
|
||||
|
||||
**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7`
|
||||
|
||||
**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1`
|
||||
|
||||
**iFlow (`if/`)** — FREE: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
|
||||
|
||||
**Qwen (`qw/`)** — FREE: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
|
||||
|
||||
**Kiro (`kr/`)** — FREE: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
|
||||
|
||||
**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`
|
||||
|
||||
**Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct`
|
||||
|
||||
**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini`
|
||||
|
||||
**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`
|
||||
|
||||
**Perplexity (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
|
||||
|
||||
**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`
|
||||
|
||||
**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`
|
||||
|
||||
**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b`
|
||||
|
||||
**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024`
|
||||
|
||||
**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## 🧩 Advanced Features
|
||||
|
||||
### Custom Models
|
||||
|
||||
Add any model ID to any provider without waiting for an app update:
|
||||
|
||||
```bash
|
||||
# Via API
|
||||
curl -X POST http://localhost:20128/api/provider-models \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"provider": "openai", "modelId": "gpt-4.5-preview", "modelName": "GPT-4.5 Preview"}'
|
||||
|
||||
# List: curl http://localhost:20128/api/provider-models?provider=openai
|
||||
# Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview"
|
||||
```
|
||||
|
||||
Or use Dashboard: **Providers → [Provider] → Custom Models**.
|
||||
|
||||
### Dedicated Provider Routes
|
||||
|
||||
Route requests directly to a specific provider with model validation:
|
||||
|
||||
```bash
|
||||
POST http://localhost:20128/v1/providers/openai/chat/completions
|
||||
POST http://localhost:20128/v1/providers/openai/embeddings
|
||||
POST http://localhost:20128/v1/providers/fireworks/images/generations
|
||||
```
|
||||
|
||||
The provider prefix is auto-added if missing. Mismatched models return `400`.
|
||||
|
||||
### Network Proxy Configuration
|
||||
|
||||
```bash
|
||||
# Set global proxy
|
||||
curl -X PUT http://localhost:20128/api/settings/proxy \
|
||||
-d '{"global": {"type":"http","host":"proxy.example.com","port":"8080"}}'
|
||||
|
||||
# Per-provider proxy
|
||||
curl -X PUT http://localhost:20128/api/settings/proxy \
|
||||
-d '{"providers": {"openai": {"type":"socks5","host":"proxy.example.com","port":"1080"}}}'
|
||||
|
||||
# Test proxy
|
||||
curl -X POST http://localhost:20128/api/settings/proxy/test \
|
||||
-d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'
|
||||
```
|
||||
|
||||
**Precedence:** Key-specific → Combo-specific → Provider-specific → Global → Environment.
|
||||
|
||||
### Model Catalog API
|
||||
|
||||
```bash
|
||||
curl http://localhost:20128/api/models/catalog
|
||||
```
|
||||
|
||||
Returns models grouped by provider with types (`chat`, `embedding`, `image`).
|
||||
|
||||
### Cloud Sync
|
||||
|
||||
- Sync providers, combos, and settings across devices
|
||||
- Automatic background sync with timeout + fail-fast
|
||||
- Prefer server-side `BASE_URL`/`CLOUD_URL` in production
|
||||
|
||||
### LLM Gateway Intelligence (Phase 9)
|
||||
|
||||
- **Semantic Cache** — Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`)
|
||||
- **Request Idempotency** — Deduplicates requests within 5s via `Idempotency-Key` or `X-Request-Id` header
|
||||
- **Progress Tracking** — Opt-in SSE `event: progress` events via `X-OmniRoute-Progress: true` header
|
||||
|
||||
---
|
||||
|
||||
### Translator Playground
|
||||
|
||||
Access via **Dashboard → Translator**. Debug and visualize how OmniRoute translates API requests between providers.
|
||||
|
||||
| Mode | Purpose |
|
||||
| ---------------- | -------------------------------------------------------------------------------------- |
|
||||
| **Playground** | Select source/target formats, paste a request, and see the translated output instantly |
|
||||
| **Chat Tester** | Send live chat messages through the proxy and inspect the full request/response cycle |
|
||||
| **Test Bench** | Run batch tests across multiple format combinations to verify translation correctness |
|
||||
| **Live Monitor** | Watch real-time translations as requests flow through the proxy |
|
||||
|
||||
**Use cases:**
|
||||
|
||||
- Debug why a specific client/provider combination fails
|
||||
- Verify that thinking tags, tool calls, and system prompts translate correctly
|
||||
- Compare format differences between OpenAI, Claude, Gemini, and Responses API formats
|
||||
|
||||
---
|
||||
|
||||
### Routing Strategies
|
||||
|
||||
Configure via **Dashboard → Settings → Routing**.
|
||||
|
||||
| Strategy | Description |
|
||||
| ------------------------------ | ------------------------------------------------------------------------------------------------ |
|
||||
| **Fill First** | Uses accounts in priority order — primary account handles all requests until unavailable |
|
||||
| **Round Robin** | Cycles through all accounts with a configurable sticky limit (default: 3 calls per account) |
|
||||
| **P2C (Power of Two Choices)** | Picks 2 random accounts and routes to the healthier one — balances load with awareness of health |
|
||||
| **Random** | Randomly selects an account for each request using Fisher-Yates shuffle |
|
||||
| **Least Used** | Routes to the account with the oldest `lastUsedAt` timestamp, distributing traffic evenly |
|
||||
| **Cost Optimized** | Routes to the account with the lowest priority value, optimizing for lowest-cost providers |
|
||||
|
||||
#### Wildcard Model Aliases
|
||||
|
||||
Create wildcard patterns to remap model names:
|
||||
|
||||
```
|
||||
Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929
|
||||
Pattern: gpt-* → Target: gh/gpt-5.1-codex
|
||||
```
|
||||
|
||||
Wildcards support `*` (any characters) and `?` (single character).
|
||||
|
||||
#### Fallback Chains
|
||||
|
||||
Define global fallback chains that apply across all requests:
|
||||
|
||||
```
|
||||
Chain: production-fallback
|
||||
1. cc/claude-opus-4-6
|
||||
2. gh/gpt-5.1-codex
|
||||
3. glm/glm-4.7
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Resilience & Circuit Breakers
|
||||
|
||||
Configure via **Dashboard → Settings → Resilience**.
|
||||
|
||||
OmniRoute implements provider-level resilience with four components:
|
||||
|
||||
1. **Provider Profiles** — Per-provider configuration for:
|
||||
- Failure threshold (how many failures before opening)
|
||||
- Cooldown duration
|
||||
- Rate limit detection sensitivity
|
||||
- Exponential backoff parameters
|
||||
|
||||
2. **Editable Rate Limits** — System-level defaults configurable in the dashboard:
|
||||
- **Requests Per Minute (RPM)** — Maximum requests per minute per account
|
||||
- **Min Time Between Requests** — Minimum gap in milliseconds between requests
|
||||
- **Max Concurrent Requests** — Maximum simultaneous requests per account
|
||||
- Click **Edit** to modify, then **Save** or **Cancel**. Values persist via the resilience API.
|
||||
|
||||
3. **Circuit Breaker** — Tracks failures per provider and automatically opens the circuit when a threshold is reached:
|
||||
- **CLOSED** (Healthy) — Requests flow normally
|
||||
- **OPEN** — Provider is temporarily blocked after repeated failures
|
||||
- **HALF_OPEN** — Testing if provider has recovered
|
||||
|
||||
4. **Policies & Locked Identifiers** — Shows circuit breaker status and locked identifiers with force-unlock capability.
|
||||
|
||||
5. **Rate Limit Auto-Detection** — Monitors `429` and `Retry-After` headers to proactively avoid hitting provider rate limits.
|
||||
|
||||
**Pro Tip:** Use **Reset All** button to clear all circuit breakers and cooldowns when a provider recovers from an outage.
|
||||
|
||||
---
|
||||
|
||||
### Database Export / Import
|
||||
|
||||
Manage database backups in **Dashboard → Settings → System & Storage**.
|
||||
|
||||
| Action | Description |
|
||||
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| **Export Database** | Downloads the current SQLite database as a `.sqlite` file |
|
||||
| **Export All (.tar.gz)** | Downloads a full backup archive including: database, settings, combos, provider connections (no credentials), API key metadata |
|
||||
| **Import Database** | Upload a `.sqlite` file to replace the current database. A pre-import backup is automatically created |
|
||||
|
||||
```bash
|
||||
# API: Export database
|
||||
curl -o backup.sqlite http://localhost:20128/api/db-backups/export
|
||||
|
||||
# API: Export all (full archive)
|
||||
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll
|
||||
|
||||
# API: Import database
|
||||
curl -X POST http://localhost:20128/api/db-backups/import \
|
||||
-F "file=@backup.sqlite"
|
||||
```
|
||||
|
||||
**Import Validation:** The imported file is validated for integrity (SQLite pragma check), required tables (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), and size (max 100MB).
|
||||
|
||||
**Use Cases:**
|
||||
|
||||
- Migrate OmniRoute between machines
|
||||
- Create external backups for disaster recovery
|
||||
- Share configurations between team members (export all → share archive)
|
||||
|
||||
---
|
||||
|
||||
### Settings Dashboard
|
||||
|
||||
The settings page is organized into 5 tabs for easy navigation:
|
||||
|
||||
| Tab | Contents |
|
||||
| -------------- | ---------------------------------------------------------------------------------------------- |
|
||||
| **Security** | Login/Password settings and IP Access Control (allowlist/blocklist) |
|
||||
| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults |
|
||||
| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers |
|
||||
| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats |
|
||||
| **Advanced** | Global proxy configuration (HTTP/SOCKS5) |
|
||||
|
||||
---
|
||||
|
||||
### Costs & Budget Management
|
||||
|
||||
Access via **Dashboard → Costs**.
|
||||
|
||||
| Tab | Purpose |
|
||||
| ----------- | ---------------------------------------------------------------------------------------- |
|
||||
| **Budget** | Set spending limits per API key with daily/weekly/monthly budgets and real-time tracking |
|
||||
| **Pricing** | View and edit model pricing entries — cost per 1K input/output tokens per provider |
|
||||
|
||||
```bash
|
||||
# API: Set a budget
|
||||
curl -X POST http://localhost:20128/api/usage/budget \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"keyId": "key-123", "limit": 50.00, "period": "monthly"}'
|
||||
|
||||
# API: Get current budget status
|
||||
curl http://localhost:20128/api/usage/budget
|
||||
```
|
||||
|
||||
**Cost Tracking:** Every request logs token usage and calculates cost using the pricing table. View breakdowns in **Dashboard → Usage** by provider, model, and API key.
|
||||
|
||||
---
|
||||
|
||||
### Audio Transcription
|
||||
|
||||
OmniRoute supports audio transcription via the OpenAI-compatible endpoint:
|
||||
|
||||
```bash
|
||||
POST /v1/audio/transcriptions
|
||||
Authorization: Bearer your-api-key
|
||||
Content-Type: multipart/form-data
|
||||
|
||||
# Example with curl
|
||||
curl -X POST http://localhost:20128/v1/audio/transcriptions \
|
||||
-H "Authorization: Bearer your-api-key" \
|
||||
-F "file=@audio.mp3" \
|
||||
-F "model=deepgram/nova-3"
|
||||
```
|
||||
|
||||
Available providers: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`).
|
||||
|
||||
Supported audio formats: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
|
||||
|
||||
---
|
||||
|
||||
### Combo Balancing Strategies
|
||||
|
||||
Configure per-combo balancing in **Dashboard → Combos → Create/Edit → Strategy**.
|
||||
|
||||
| Strategy | Description |
|
||||
| ------------------ | ------------------------------------------------------------------------ |
|
||||
| **Round-Robin** | Rotates through models sequentially |
|
||||
| **Priority** | Always tries the first model; falls back only on error |
|
||||
| **Random** | Picks a random model from the combo for each request |
|
||||
| **Weighted** | Routes proportionally based on assigned weights per model |
|
||||
| **Least-Used** | Routes to the model with the fewest recent requests (uses combo metrics) |
|
||||
| **Cost-Optimized** | Routes to the cheapest available model (uses pricing table) |
|
||||
|
||||
Global combo defaults can be set in **Dashboard → Settings → Routing → Combo Defaults**.
|
||||
|
||||
---
|
||||
|
||||
### Health Dashboard
|
||||
|
||||
Access via **Dashboard → Health**. Real-time system health overview with 6 cards:
|
||||
|
||||
| Card | What It Shows |
|
||||
| --------------------- | ----------------------------------------------------------- |
|
||||
| **System Status** | Uptime, version, memory usage, data directory |
|
||||
| **Provider Health** | Per-provider circuit breaker state (Closed/Open/Half-Open) |
|
||||
| **Rate Limits** | Active rate limit cooldowns per account with remaining time |
|
||||
| **Active Lockouts** | Providers temporarily blocked by the lockout policy |
|
||||
| **Signature Cache** | Deduplication cache stats (active keys, hit rate) |
|
||||
| **Latency Telemetry** | p50/p95/p99 latency aggregation per provider |
|
||||
|
||||
**Pro Tip:** The Health page auto-refreshes every 10 seconds. Use the circuit breaker card to identify which providers are experiencing issues.
|
||||
399
docs/VM_DEPLOYMENT_GUIDE.md
Normal file
399
docs/VM_DEPLOYMENT_GUIDE.md
Normal file
@@ -0,0 +1,399 @@
|
||||
# OmniRoute — Guia de Deploy em VM com Cloudflare
|
||||
|
||||
Guia completo para instalar e configurar o OmniRoute em uma VM (VPS) com domínio gerenciado via Cloudflare.
|
||||
|
||||
---
|
||||
|
||||
## Pré-Requisitos
|
||||
|
||||
| Item | Mínimo | Recomendado |
|
||||
| ----------- | ------------------------ | ---------------- |
|
||||
| **CPU** | 1 vCPU | 2 vCPU |
|
||||
| **RAM** | 1 GB | 2 GB |
|
||||
| **Disco** | 10 GB SSD | 25 GB SSD |
|
||||
| **SO** | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS |
|
||||
| **Domínio** | Registrado no Cloudflare | — |
|
||||
| **Docker** | Docker Engine 24+ | Docker 27+ |
|
||||
|
||||
**Providers testados**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail.
|
||||
|
||||
---
|
||||
|
||||
## 1. Configurar a VM
|
||||
|
||||
### 1.1 Criar a instância
|
||||
|
||||
No seu provider de VPS preferido:
|
||||
|
||||
- Escolha Ubuntu 24.04 LTS
|
||||
- Selecione o plano mínimo (1 vCPU / 1 GB RAM)
|
||||
- Defina uma senha forte para root ou configure SSH key
|
||||
- Anote o **IP público** (ex: `203.0.113.10`)
|
||||
|
||||
### 1.2 Conectar via SSH
|
||||
|
||||
```bash
|
||||
ssh root@203.0.113.10
|
||||
```
|
||||
|
||||
### 1.3 Atualizar o sistema
|
||||
|
||||
```bash
|
||||
apt update && apt upgrade -y
|
||||
```
|
||||
|
||||
### 1.4 Instalar Docker
|
||||
|
||||
```bash
|
||||
# Instalar dependências
|
||||
apt install -y ca-certificates curl gnupg
|
||||
|
||||
# Adicionar repositório oficial do Docker
|
||||
install -m 0755 -d /etc/apt/keyrings
|
||||
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg
|
||||
chmod a+r /etc/apt/keyrings/docker.gpg
|
||||
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null
|
||||
apt update
|
||||
apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
|
||||
```
|
||||
|
||||
### 1.5 Instalar nginx
|
||||
|
||||
```bash
|
||||
apt install -y nginx
|
||||
```
|
||||
|
||||
### 1.6 Configurar Firewall (UFW)
|
||||
|
||||
```bash
|
||||
ufw default deny incoming
|
||||
ufw default allow outgoing
|
||||
ufw allow 22/tcp # SSH
|
||||
ufw allow 80/tcp # HTTP (redirect)
|
||||
ufw allow 443/tcp # HTTPS
|
||||
ufw enable
|
||||
```
|
||||
|
||||
> **Dica**: Para segurança máxima, restrinja as portas 80 e 443 apenas para IPs da Cloudflare. Veja a seção [Segurança Avançada](#segurança-avançada).
|
||||
|
||||
---
|
||||
|
||||
## 2. Instalar o OmniRoute
|
||||
|
||||
### 2.1 Criar diretório de configuração
|
||||
|
||||
```bash
|
||||
mkdir -p /opt/omniroute
|
||||
```
|
||||
|
||||
### 2.2 Criar arquivo de variáveis de ambiente
|
||||
|
||||
```bash
|
||||
cat > /opt/omniroute/.env << 'EOF'
|
||||
# === Segurança ===
|
||||
JWT_SECRET=ALTERE-PARA-CHAVE-SECRETA-UNICA-64-CHARS
|
||||
INITIAL_PASSWORD=SuaSenhaSegura123!
|
||||
API_KEY_SECRET=ALTERE-PARA-OUTRA-CHAVE-SECRETA
|
||||
STORAGE_ENCRYPTION_KEY=ALTERE-PARA-TERCEIRA-CHAVE-SECRETA
|
||||
STORAGE_ENCRYPTION_KEY_VERSION=v1
|
||||
MACHINE_ID_SALT=ALTERE-PARA-SALT-UNICO
|
||||
|
||||
# === App ===
|
||||
PORT=20128
|
||||
NODE_ENV=production
|
||||
HOSTNAME=0.0.0.0
|
||||
DATA_DIR=/app/data
|
||||
STORAGE_DRIVER=sqlite
|
||||
ENABLE_REQUEST_LOGS=true
|
||||
AUTH_COOKIE_SECURE=false
|
||||
REQUIRE_API_KEY=false
|
||||
|
||||
# === Domain (altere para seu domínio) ===
|
||||
BASE_URL=https://llms.seudominio.com
|
||||
NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com
|
||||
|
||||
# === Cloud Sync (opcional) ===
|
||||
# CLOUD_URL=https://cloud.omniroute.online
|
||||
# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online
|
||||
EOF
|
||||
```
|
||||
|
||||
> ⚠️ **IMPORTANTE**: Gere chaves secretas únicas! Use `openssl rand -hex 32` para cada chave.
|
||||
|
||||
### 2.3 Iniciar o container
|
||||
|
||||
```bash
|
||||
docker pull diegosouzapw/omniroute:latest
|
||||
|
||||
docker run -d \
|
||||
--name omniroute \
|
||||
--restart unless-stopped \
|
||||
--env-file /opt/omniroute/.env \
|
||||
-p 20128:20128 \
|
||||
-v omniroute-data:/app/data \
|
||||
diegosouzapw/omniroute:latest
|
||||
```
|
||||
|
||||
### 2.4 Verificar se está rodando
|
||||
|
||||
```bash
|
||||
docker ps | grep omniroute
|
||||
docker logs omniroute --tail 20
|
||||
```
|
||||
|
||||
Deve exibir: `[DB] SQLite database ready` e `listening on port 20128`.
|
||||
|
||||
---
|
||||
|
||||
## 3. Configurar nginx (Reverse Proxy)
|
||||
|
||||
### 3.1 Gerar certificado SSL (Cloudflare Origin)
|
||||
|
||||
No painel da Cloudflare:
|
||||
|
||||
1. Vá em **SSL/TLS → Origin Server**
|
||||
2. Clique **Create Certificate**
|
||||
3. Deixe os padrões (15 anos, \*.seudominio.com)
|
||||
4. Copie o **Origin Certificate** e a **Private Key**
|
||||
|
||||
```bash
|
||||
mkdir -p /etc/nginx/ssl
|
||||
|
||||
# Colar o certificado
|
||||
nano /etc/nginx/ssl/origin.crt
|
||||
|
||||
# Colar a chave privada
|
||||
nano /etc/nginx/ssl/origin.key
|
||||
|
||||
chmod 600 /etc/nginx/ssl/origin.key
|
||||
```
|
||||
|
||||
### 3.2 Configuração do nginx
|
||||
|
||||
```bash
|
||||
cat > /etc/nginx/sites-available/omniroute << 'NGINX'
|
||||
# Default server — bloqueia acesso direto por IP
|
||||
server {
|
||||
listen 80 default_server;
|
||||
listen [::]:80 default_server;
|
||||
listen 443 ssl default_server;
|
||||
listen [::]:443 ssl default_server;
|
||||
ssl_certificate /etc/nginx/ssl/origin.crt;
|
||||
ssl_certificate_key /etc/nginx/ssl/origin.key;
|
||||
server_name _;
|
||||
return 444;
|
||||
}
|
||||
|
||||
# OmniRoute — HTTPS
|
||||
server {
|
||||
listen 443 ssl;
|
||||
listen [::]:443 ssl;
|
||||
server_name llms.seudominio.com; # Altere para seu domínio
|
||||
|
||||
ssl_certificate /etc/nginx/ssl/origin.crt;
|
||||
ssl_certificate_key /etc/nginx/ssl/origin.key;
|
||||
ssl_protocols TLSv1.2 TLSv1.3;
|
||||
|
||||
client_max_body_size 100M;
|
||||
|
||||
location / {
|
||||
proxy_pass http://127.0.0.1:20128;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
|
||||
# WebSocket support
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection "upgrade";
|
||||
|
||||
# SSE (Server-Sent Events) — streaming AI responses
|
||||
proxy_buffering off;
|
||||
proxy_cache off;
|
||||
proxy_read_timeout 300s;
|
||||
proxy_send_timeout 300s;
|
||||
}
|
||||
}
|
||||
|
||||
# HTTP → HTTPS redirect
|
||||
server {
|
||||
listen 80;
|
||||
listen [::]:80;
|
||||
server_name llms.seudominio.com;
|
||||
return 301 https://$server_name$request_uri;
|
||||
}
|
||||
NGINX
|
||||
```
|
||||
|
||||
### 3.3 Ativar e testar
|
||||
|
||||
```bash
|
||||
# Remover config padrão
|
||||
rm -f /etc/nginx/sites-enabled/default
|
||||
|
||||
# Ativar OmniRoute
|
||||
ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute
|
||||
|
||||
# Testar e recarregar
|
||||
nginx -t && systemctl reload nginx
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Configurar Cloudflare DNS
|
||||
|
||||
### 4.1 Adicionar registro DNS
|
||||
|
||||
No painel da Cloudflare → DNS:
|
||||
|
||||
| Type | Name | Content | Proxy |
|
||||
| ---- | ------ | ------------------------- | ---------- |
|
||||
| A | `llms` | `203.0.113.10` (IP da VM) | ✅ Proxied |
|
||||
|
||||
### 4.2 Configurar SSL
|
||||
|
||||
Em **SSL/TLS → Overview**:
|
||||
|
||||
- Modo: **Full (Strict)**
|
||||
|
||||
Em **SSL/TLS → Edge Certificates**:
|
||||
|
||||
- Always Use HTTPS: ✅ On
|
||||
- Minimum TLS Version: TLS 1.2
|
||||
- Automatic HTTPS Rewrites: ✅ On
|
||||
|
||||
### 4.3 Testar
|
||||
|
||||
```bash
|
||||
curl -sI https://llms.seudominio.com/health
|
||||
# Deve retornar HTTP/2 200
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Operações e Manutenção
|
||||
|
||||
### Atualizar para nova versão
|
||||
|
||||
```bash
|
||||
docker pull diegosouzapw/omniroute:latest
|
||||
docker stop omniroute && docker rm omniroute
|
||||
docker run -d --name omniroute --restart unless-stopped \
|
||||
--env-file /opt/omniroute/.env \
|
||||
-p 20128:20128 \
|
||||
-v omniroute-data:/app/data \
|
||||
diegosouzapw/omniroute:latest
|
||||
```
|
||||
|
||||
### Ver logs
|
||||
|
||||
```bash
|
||||
docker logs -f omniroute # Stream em tempo real
|
||||
docker logs omniroute --tail 50 # Últimas 50 linhas
|
||||
```
|
||||
|
||||
### Backup manual do banco
|
||||
|
||||
```bash
|
||||
# Copiar dados do volume para o host
|
||||
docker cp omniroute:/app/data ./backup-$(date +%F)
|
||||
|
||||
# Ou comprimir todo o volume
|
||||
docker run --rm -v omniroute-data:/data -v $(pwd):/backup \
|
||||
alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data
|
||||
```
|
||||
|
||||
### Restaurar de backup
|
||||
|
||||
```bash
|
||||
docker stop omniroute
|
||||
docker run --rm -v omniroute-data:/data -v $(pwd):/backup \
|
||||
alpine sh -c "rm -rf /data/* && tar xzf /backup/omniroute-data-YYYY-MM-DD.tar.gz -C /"
|
||||
docker start omniroute
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Segurança Avançada
|
||||
|
||||
### Restringir nginx para Cloudflare IPs
|
||||
|
||||
```bash
|
||||
cat > /etc/nginx/cloudflare-ips.conf << 'CF'
|
||||
# Cloudflare IPv4 ranges — atualizar periodicamente
|
||||
# https://www.cloudflare.com/ips-v4/
|
||||
set_real_ip_from 173.245.48.0/20;
|
||||
set_real_ip_from 103.21.244.0/22;
|
||||
set_real_ip_from 103.22.200.0/22;
|
||||
set_real_ip_from 103.31.4.0/22;
|
||||
set_real_ip_from 141.101.64.0/18;
|
||||
set_real_ip_from 108.162.192.0/18;
|
||||
set_real_ip_from 190.93.240.0/20;
|
||||
set_real_ip_from 188.114.96.0/20;
|
||||
set_real_ip_from 197.234.240.0/22;
|
||||
set_real_ip_from 198.41.128.0/17;
|
||||
set_real_ip_from 162.158.0.0/15;
|
||||
set_real_ip_from 104.16.0.0/13;
|
||||
set_real_ip_from 104.24.0.0/14;
|
||||
set_real_ip_from 172.64.0.0/13;
|
||||
set_real_ip_from 131.0.72.0/22;
|
||||
real_ip_header CF-Connecting-IP;
|
||||
CF
|
||||
```
|
||||
|
||||
Adicionar no `nginx.conf` dentro do bloco `http {}`:
|
||||
|
||||
```nginx
|
||||
include /etc/nginx/cloudflare-ips.conf;
|
||||
```
|
||||
|
||||
### Install fail2ban
|
||||
|
||||
```bash
|
||||
apt install -y fail2ban
|
||||
systemctl enable fail2ban
|
||||
systemctl start fail2ban
|
||||
|
||||
# Verificar status
|
||||
fail2ban-client status sshd
|
||||
```
|
||||
|
||||
### Bloquear acesso direto na porta do Docker
|
||||
|
||||
```bash
|
||||
# Impedir acesso externo direto à porta 20128
|
||||
iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP
|
||||
iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT
|
||||
|
||||
# Persistir as regras
|
||||
apt install -y iptables-persistent
|
||||
netfilter-persistent save
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Deploy do Cloud Worker (Opcional)
|
||||
|
||||
Para acesso remoto via Cloudflare Workers (sem expor a VM diretamente):
|
||||
|
||||
```bash
|
||||
# No repositório local
|
||||
cd omnirouteCloud
|
||||
npm install
|
||||
npx wrangler login
|
||||
npx wrangler deploy
|
||||
```
|
||||
|
||||
Ver documentação completa em [omnirouteCloud/README.md](../omnirouteCloud/README.md).
|
||||
|
||||
---
|
||||
|
||||
## Resumo de Portas
|
||||
|
||||
| Porta | Serviço | Acesso |
|
||||
| ----- | ----------- | ----------------------------- |
|
||||
| 22 | SSH | Público (com fail2ban) |
|
||||
| 80 | nginx HTTP | Redirect → HTTPS |
|
||||
| 443 | nginx HTTPS | Via Cloudflare Proxy |
|
||||
| 20128 | OmniRoute | Somente localhost (via nginx) |
|
||||
2198
docs/openapi.yaml
Normal file
2198
docs/openapi.yaml
Normal file
File diff suppressed because it is too large
Load Diff
BIN
docs/screenshots/01-providers.png
Normal file
BIN
docs/screenshots/01-providers.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 149 KiB |
BIN
docs/screenshots/02-combos.png
Normal file
BIN
docs/screenshots/02-combos.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 136 KiB |
BIN
docs/screenshots/03-analytics.png
Normal file
BIN
docs/screenshots/03-analytics.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 153 KiB |
BIN
docs/screenshots/04-health.png
Normal file
BIN
docs/screenshots/04-health.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 119 KiB |
BIN
docs/screenshots/05-translator.png
Normal file
BIN
docs/screenshots/05-translator.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 112 KiB |
BIN
docs/screenshots/06-settings.png
Normal file
BIN
docs/screenshots/06-settings.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 128 KiB |
BIN
docs/screenshots/07-cli-tools.png
Normal file
BIN
docs/screenshots/07-cli-tools.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 67 KiB |
BIN
docs/screenshots/08-usage.png
Normal file
BIN
docs/screenshots/08-usage.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 220 KiB |
BIN
docs/screenshots/09-endpoint.png
Normal file
BIN
docs/screenshots/09-endpoint.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 125 KiB |
30
eslint.config.mjs
Normal file
30
eslint.config.mjs
Normal file
@@ -0,0 +1,30 @@
|
||||
import nextVitals from "eslint-config-next/core-web-vitals";
|
||||
|
||||
/** @type {import("eslint").Linter.Config[]} */
|
||||
const eslintConfig = [
|
||||
...nextVitals,
|
||||
// FASE-02: Security rules
|
||||
{
|
||||
rules: {
|
||||
"no-eval": "error",
|
||||
"no-implied-eval": "error",
|
||||
"no-new-func": "error",
|
||||
},
|
||||
},
|
||||
// Global ignores
|
||||
{
|
||||
ignores: [
|
||||
".next/**",
|
||||
"out/**",
|
||||
"build/**",
|
||||
"next-env.d.ts",
|
||||
"tests/**",
|
||||
"scripts/**",
|
||||
"bin/**",
|
||||
"node_modules/**",
|
||||
"open-sse/**",
|
||||
],
|
||||
},
|
||||
];
|
||||
|
||||
export default eslintConfig;
|
||||
BIN
images/omniroute.png
Normal file
BIN
images/omniroute.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 362 KiB |
66
next.config.mjs
Normal file
66
next.config.mjs
Normal file
@@ -0,0 +1,66 @@
|
||||
/** @type {import('next').NextConfig} */
|
||||
const nextConfig = {
|
||||
turbopack: {},
|
||||
output: "standalone",
|
||||
transpilePackages: ["@omniroute/open-sse"],
|
||||
allowedDevOrigins: ["192.168.*"],
|
||||
typescript: {
|
||||
// Migration Phase: ignore TS errors during build.
|
||||
// Remove after all 984 type errors are resolved.
|
||||
ignoreBuildErrors: true,
|
||||
},
|
||||
images: {
|
||||
unoptimized: true,
|
||||
},
|
||||
|
||||
// NEXT_PUBLIC_CLOUD_URL is set in .env — do NOT hardcode here (it overrides .env)
|
||||
webpack: (config, { isServer }) => {
|
||||
// Ignore fs/path modules in browser bundle
|
||||
if (!isServer) {
|
||||
config.resolve.fallback = {
|
||||
...config.resolve.fallback,
|
||||
fs: false,
|
||||
path: false,
|
||||
};
|
||||
}
|
||||
return config;
|
||||
},
|
||||
async rewrites() {
|
||||
return [
|
||||
{
|
||||
source: "/chat/completions",
|
||||
destination: "/api/v1/chat/completions",
|
||||
},
|
||||
{
|
||||
source: "/responses",
|
||||
destination: "/api/v1/responses",
|
||||
},
|
||||
{
|
||||
source: "/models",
|
||||
destination: "/api/v1/models",
|
||||
},
|
||||
{
|
||||
source: "/v1/v1/:path*",
|
||||
destination: "/api/v1/:path*",
|
||||
},
|
||||
{
|
||||
source: "/v1/v1",
|
||||
destination: "/api/v1",
|
||||
},
|
||||
{
|
||||
source: "/codex/:path*",
|
||||
destination: "/api/v1/responses",
|
||||
},
|
||||
{
|
||||
source: "/v1/:path*",
|
||||
destination: "/api/v1/:path*",
|
||||
},
|
||||
{
|
||||
source: "/v1",
|
||||
destination: "/api/v1",
|
||||
},
|
||||
];
|
||||
},
|
||||
};
|
||||
|
||||
export default nextConfig;
|
||||
8
open-sse/.npmignore
Normal file
8
open-sse/.npmignore
Normal file
@@ -0,0 +1,8 @@
|
||||
node_modules/
|
||||
*.log
|
||||
.DS_Store
|
||||
test/
|
||||
*.test.js
|
||||
.env
|
||||
.env.*
|
||||
|
||||
183
open-sse/config/audioRegistry.ts
Normal file
183
open-sse/config/audioRegistry.ts
Normal file
@@ -0,0 +1,183 @@
|
||||
/**
|
||||
* Audio Provider Registry
|
||||
*
|
||||
* Defines providers that support audio endpoints:
|
||||
* - /v1/audio/transcriptions (Whisper API)
|
||||
* - /v1/audio/speech (TTS API)
|
||||
*/
|
||||
|
||||
interface AudioModel {
|
||||
id: string;
|
||||
name: string;
|
||||
}
|
||||
|
||||
interface AudioProvider {
|
||||
id: string;
|
||||
baseUrl: string;
|
||||
authType: string;
|
||||
authHeader: string;
|
||||
format?: string;
|
||||
async?: boolean;
|
||||
models: AudioModel[];
|
||||
}
|
||||
|
||||
export const AUDIO_TRANSCRIPTION_PROVIDERS: Record<string, AudioProvider> = {
|
||||
openai: {
|
||||
id: "openai",
|
||||
baseUrl: "https://api.openai.com/v1/audio/transcriptions",
|
||||
authType: "apikey",
|
||||
authHeader: "bearer",
|
||||
models: [
|
||||
{ id: "whisper-1", name: "Whisper 1" },
|
||||
{ id: "gpt-4o-transcription", name: "GPT-4o Transcription" },
|
||||
],
|
||||
},
|
||||
|
||||
groq: {
|
||||
id: "groq",
|
||||
baseUrl: "https://api.groq.com/openai/v1/audio/transcriptions",
|
||||
authType: "apikey",
|
||||
authHeader: "bearer",
|
||||
models: [
|
||||
{ id: "whisper-large-v3", name: "Whisper Large v3" },
|
||||
{ id: "whisper-large-v3-turbo", name: "Whisper Large v3 Turbo" },
|
||||
{ id: "distil-whisper-large-v3-en", name: "Distil Whisper Large v3 EN" },
|
||||
],
|
||||
},
|
||||
|
||||
deepgram: {
|
||||
id: "deepgram",
|
||||
baseUrl: "https://api.deepgram.com/v1/listen",
|
||||
authType: "apikey",
|
||||
authHeader: "token",
|
||||
format: "deepgram",
|
||||
models: [
|
||||
{ id: "nova-3", name: "Nova 3" },
|
||||
{ id: "nova-2", name: "Nova 2" },
|
||||
{ id: "whisper-large", name: "Whisper Large" },
|
||||
],
|
||||
},
|
||||
|
||||
assemblyai: {
|
||||
id: "assemblyai",
|
||||
baseUrl: "https://api.assemblyai.com/v2/transcript",
|
||||
authType: "apikey",
|
||||
authHeader: "bearer",
|
||||
async: true,
|
||||
format: "assemblyai",
|
||||
models: [
|
||||
{ id: "universal-3-pro", name: "Universal 3 Pro" },
|
||||
{ id: "universal-2", name: "Universal 2" },
|
||||
],
|
||||
},
|
||||
};
|
||||
|
||||
export const AUDIO_SPEECH_PROVIDERS: Record<string, AudioProvider> = {
|
||||
openai: {
|
||||
id: "openai",
|
||||
baseUrl: "https://api.openai.com/v1/audio/speech",
|
||||
authType: "apikey",
|
||||
authHeader: "bearer",
|
||||
models: [
|
||||
{ id: "tts-1", name: "TTS 1" },
|
||||
{ id: "tts-1-hd", name: "TTS 1 HD" },
|
||||
{ id: "gpt-4o-mini-tts", name: "GPT-4o Mini TTS" },
|
||||
],
|
||||
},
|
||||
|
||||
hyperbolic: {
|
||||
id: "hyperbolic",
|
||||
baseUrl: "https://api.hyperbolic.xyz/v1/audio/generation",
|
||||
authType: "apikey",
|
||||
authHeader: "bearer",
|
||||
format: "hyperbolic",
|
||||
models: [{ id: "melo-tts", name: "Melo TTS" }],
|
||||
},
|
||||
|
||||
deepgram: {
|
||||
id: "deepgram",
|
||||
baseUrl: "https://api.deepgram.com/v1/speak",
|
||||
authType: "apikey",
|
||||
authHeader: "token",
|
||||
format: "deepgram",
|
||||
models: [
|
||||
{ id: "aura-asteria-en", name: "Aura Asteria (EN)" },
|
||||
{ id: "aura-luna-en", name: "Aura Luna (EN)" },
|
||||
{ id: "aura-stella-en", name: "Aura Stella (EN)" },
|
||||
],
|
||||
},
|
||||
};
|
||||
|
||||
/**
|
||||
* Get transcription provider config by ID
|
||||
*/
|
||||
export function getTranscriptionProvider(providerId: string): AudioProvider | null {
|
||||
return AUDIO_TRANSCRIPTION_PROVIDERS[providerId] || null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get speech provider config by ID
|
||||
*/
|
||||
export function getSpeechProvider(providerId: string): AudioProvider | null {
|
||||
return AUDIO_SPEECH_PROVIDERS[providerId] || null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Parse audio model string (format: "provider/model" or just "model")
|
||||
*/
|
||||
function parseAudioModel(modelStr: string | null, registry: Record<string, AudioProvider>): { provider: string | null; model: string | null } {
|
||||
if (!modelStr) return { provider: null, model: null };
|
||||
|
||||
for (const [providerId, config] of Object.entries(registry)) {
|
||||
if (modelStr.startsWith(providerId + "/")) {
|
||||
return { provider: providerId, model: modelStr.slice(providerId.length + 1) };
|
||||
}
|
||||
}
|
||||
|
||||
for (const [providerId, config] of Object.entries(registry)) {
|
||||
if (config.models.some((m) => m.id === modelStr)) {
|
||||
return { provider: providerId, model: modelStr };
|
||||
}
|
||||
}
|
||||
|
||||
return { provider: null, model: modelStr };
|
||||
}
|
||||
|
||||
export function parseTranscriptionModel(modelStr: string | null) {
|
||||
return parseAudioModel(modelStr, AUDIO_TRANSCRIPTION_PROVIDERS);
|
||||
}
|
||||
|
||||
export function parseSpeechModel(modelStr: string | null) {
|
||||
return parseAudioModel(modelStr, AUDIO_SPEECH_PROVIDERS);
|
||||
}
|
||||
|
||||
/**
|
||||
* Get all audio models as a flat list
|
||||
*/
|
||||
export function getAllAudioModels() {
|
||||
const models = [];
|
||||
|
||||
for (const [providerId, config] of Object.entries(AUDIO_TRANSCRIPTION_PROVIDERS)) {
|
||||
for (const model of config.models) {
|
||||
models.push({
|
||||
id: `${providerId}/${model.id}`,
|
||||
name: model.name,
|
||||
provider: providerId,
|
||||
subtype: "transcription",
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
for (const [providerId, config] of Object.entries(AUDIO_SPEECH_PROVIDERS)) {
|
||||
for (const model of config.models) {
|
||||
models.push({
|
||||
id: `${providerId}/${model.id}`,
|
||||
name: model.name,
|
||||
provider: providerId,
|
||||
subtype: "speech",
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
return models;
|
||||
}
|
||||
120
open-sse/config/codexInstructions.ts
Normal file
120
open-sse/config/codexInstructions.ts
Normal file
@@ -0,0 +1,120 @@
|
||||
// Default instructions for Codex models
|
||||
// Source: CLIProxyAPI internal/misc/codex_instructions/
|
||||
|
||||
export const CODEX_DEFAULT_INSTRUCTIONS = `You are Codex, based on GPT-5. You are running as a coding agent in the Codex CLI on a user's computer.
|
||||
|
||||
## General
|
||||
|
||||
- When searching for text or files, prefer using \`rg\` or \`rg --files\` respectively because \`rg\` is much faster than alternatives like \`grep\`. (If the \`rg\` command is not found, then use alternatives.)
|
||||
|
||||
## Editing constraints
|
||||
|
||||
- Default to ASCII when editing or creating files. Only introduce non-ASCII or other Unicode characters when there is a clear justification and the file already uses them.
|
||||
- Add succinct code comments that explain what is going on if code is not self-explanatory. You should not add comments like "Assigns the value to the variable", but a brief comment might be useful ahead of a complex code block that the user would otherwise have to spend time parsing out. Usage of these comments should be rare.
|
||||
- Try to use apply_patch for single file edits, but it is fine to explore other options to make the edit if it does not work well. Do not use apply_patch for changes that are auto-generated (i.e. generating package.json or running a lint or format command like gofmt) or when scripting is more efficient (such as search and replacing a string across a codebase).
|
||||
- You may be in a dirty git worktree.
|
||||
* NEVER revert existing changes you did not make unless explicitly requested, since these changes were made by the user.
|
||||
* If asked to make a commit or code edits and there are unrelated changes to your work or changes that you didn't make in those files, don't revert those changes.
|
||||
* If the changes are in files you've touched recently, you should read carefully and understand how you can work with the changes rather than reverting them.
|
||||
* If the changes are in unrelated files, just ignore them and don't revert them.
|
||||
- Do not amend a commit unless explicitly requested to do so.
|
||||
- While you are working, you might notice unexpected changes that you didn't make. If this happens, STOP IMMEDIATELY and ask the user how they would like to proceed.
|
||||
- **NEVER** use destructive commands like \`git reset --hard\` or \`git checkout --\` unless specifically requested or approved by the user.
|
||||
|
||||
## Plan tool
|
||||
|
||||
When using the planning tool:
|
||||
- Skip using the planning tool for straightforward tasks (roughly the easiest 25%).
|
||||
- Do not make single-step plans.
|
||||
- When you made a plan, update it after having performed one of the sub-tasks that you shared on the plan.
|
||||
|
||||
## Codex CLI harness, sandboxing, and approvals
|
||||
|
||||
The Codex CLI harness supports several different configurations for sandboxing and escalation approvals that the user can choose from.
|
||||
|
||||
Filesystem sandboxing defines which files can be read or written. The options for \`sandbox_mode\` are:
|
||||
- **read-only**: The sandbox only permits reading files.
|
||||
- **workspace-write**: The sandbox permits reading files, and editing files in \`cwd\` and \`writable_roots\`. Editing files in other directories requires approval.
|
||||
- **danger-full-access**: No filesystem sandboxing - all commands are permitted.
|
||||
|
||||
Network sandboxing defines whether network can be accessed without approval. Options for \`network_access\` are:
|
||||
- **restricted**: Requires approval
|
||||
- **enabled**: No approval needed
|
||||
|
||||
Approvals are your mechanism to get user consent to run shell commands without the sandbox. Possible configuration options for \`approval_policy\` are
|
||||
- **untrusted**: The harness will escalate most commands for user approval, apart from a limited allowlist of safe "read" commands.
|
||||
- **on-failure**: The harness will allow all commands to run in the sandbox (if enabled), and failures will be escalated to the user for approval to run again without the sandbox.
|
||||
- **on-request**: Commands will be run in the sandbox by default, and you can specify in your tool call if you want to escalate a command to run without sandboxing. (Note that this mode is not always available. If it is, you'll see parameters for it in the \`shell\` command description.)
|
||||
- **never**: This is a non-interactive mode where you may NEVER ask the user for approval to run commands. Instead, you must always persist and work around constraints to solve the task for the user. You MUST do your utmost best to finish the task and validate your work before yielding. If this mode is paired with \`danger-full-access\`, take advantage of it to deliver the best outcome for the user. Further, in this mode, your default testing philosophy is overridden: Even if you don't see local patterns for testing, you may add tests and scripts to validate your work. Just remove them before yielding.
|
||||
|
||||
When you are running with \`approval_policy == on-request\`, and sandboxing enabled, here are scenarios where you'll need to request approval:
|
||||
- You need to run a command that writes to a directory that requires it (e.g. running tests that write to /var)
|
||||
- You need to run a GUI app (e.g., open/xdg-open/osascript) to open browsers or files.
|
||||
- You are running sandboxed and need to run a command that requires network access (e.g. installing packages)
|
||||
- If you run a command that is important to solving the user's query, but it fails because of sandboxing, rerun the command with approval. ALWAYS proceed to use the \`sandbox_permissions\` and \`justification\` parameters - do not message the user before requesting approval for the command.
|
||||
- You are about to take a potentially destructive action such as an \`rm\` or \`git reset\` that the user did not explicitly ask for
|
||||
- (for all of these, you should weigh alternative paths that do not require approval)
|
||||
|
||||
When \`sandbox_mode\` is set to read-only, you'll need to request approval for any command that isn't a read.
|
||||
|
||||
You will be told what filesystem sandboxing, network sandboxing, and approval mode are active in a developer or user message. If you are not told about this, assume that you are running with workspace-write, network sandboxing enabled, and approval on-failure.
|
||||
|
||||
Although they introduce friction to the user because your work is paused until the user responds, you should leverage them when necessary to accomplish important work. If the completing the task requires escalated permissions, Do not let these settings or the sandbox deter you from attempting to accomplish the user's task unless it is set to "never", in which case never ask for approvals.
|
||||
|
||||
When requesting approval to execute a command that will require escalated privileges:
|
||||
- Provide the \`sandbox_permissions\` parameter with the value \`"require_escalated"\`
|
||||
- Include a short, 1 sentence explanation for why you need escalated permissions in the justification parameter
|
||||
|
||||
## Special user requests
|
||||
|
||||
- If the user makes a simple request (such as asking for the time) which you can fulfill by running a terminal command (such as \`date\`), you should do so.
|
||||
- If the user asks for a "review", default to a code review mindset: prioritise identifying bugs, risks, behavioural regressions, and missing tests. Findings must be the primary focus of the response - keep summaries or overviews brief and only after enumerating the issues. Present findings first (ordered by severity with file/line references), follow with open questions or assumptions, and offer a change-summary only as a secondary detail. If no findings are discovered, state that explicitly and mention any residual risks or testing gaps.
|
||||
|
||||
## Frontend tasks
|
||||
When doing frontend design tasks, avoid collapsing into "AI slop" or safe, average-looking layouts.
|
||||
Aim for interfaces that feel intentional, bold, and a bit surprising.
|
||||
- Typography: Use expressive, purposeful fonts and avoid default stacks (Inter, Roboto, Arial, system).
|
||||
- Color & Look: Choose a clear visual direction; define CSS variables; avoid purple-on-white defaults. No purple bias or dark mode bias.
|
||||
- Motion: Use a few meaningful animations (page-load, staggered reveals) instead of generic micro-motions.
|
||||
- Background: Don't rely on flat, single-color backgrounds; use gradients, shapes, or subtle patterns to build atmosphere.
|
||||
- Overall: Avoid boilerplate layouts and interchangeable UI patterns. Vary themes, type families, and visual languages across outputs.
|
||||
- Ensure the page loads properly on both desktop and mobile
|
||||
|
||||
Exception: If working within an existing website or design system, preserve the established patterns, structure, and visual language.
|
||||
|
||||
## Presenting your work and final message
|
||||
|
||||
You are producing plain text that will later be styled by the CLI. Follow these rules exactly. Formatting should make results easy to scan, but not feel mechanical. Use judgment to decide how much structure adds value.
|
||||
|
||||
- Default: be very concise; friendly coding teammate tone.
|
||||
- Ask only when needed; suggest ideas; mirror the user's style.
|
||||
- For substantial work, summarize clearly; follow final‑answer formatting.
|
||||
- Skip heavy formatting for simple confirmations.
|
||||
- Don't dump large files you've written; reference paths only.
|
||||
- No "save/copy this file" - User is on the same machine.
|
||||
- Offer logical next steps (tests, commits, build) briefly; add verify steps if you couldn't do something.
|
||||
- For code changes:
|
||||
* Lead with a quick explanation of the change, and then give more details on the context covering where and why a change was made. Do not start this explanation with "summary", just jump right in.
|
||||
* If there are natural next steps the user may want to take, suggest them at the end of your response. Do not make suggestions if there are no natural next steps.
|
||||
* When suggesting multiple options, use numeric lists for the suggestions so the user can quickly respond with a single number.
|
||||
- The user does not command execution outputs. When asked to show the output of a command (e.g. \`git show\`), relay the important details in your answer or summarize the key lines so the user understands the result.
|
||||
|
||||
### Final answer structure and style guidelines
|
||||
|
||||
- Plain text; CLI handles styling. Use structure only when it helps scanability.
|
||||
- Headers: optional; short Title Case (1-3 words) wrapped in **…**; no blank line before the first bullet; add only if they truly help.
|
||||
- Bullets: use - ; merge related points; keep to one line when possible; 4–6 per list ordered by importance; keep phrasing consistent.
|
||||
- Monospace: backticks for commands/paths/env vars/code ids and inline examples; use for literal keyword bullets; never combine with **.
|
||||
- Code samples or multi-line snippets should be wrapped in fenced code blocks; include an info string as often as possible.
|
||||
- Structure: group related bullets; order sections general → specific → supporting; for subsections, start with a bolded keyword bullet, then items; match complexity to the task.
|
||||
- Tone: collaborative, concise, factual; present tense, active voice; self‑contained; no "above/below"; parallel wording.
|
||||
- Don'ts: no nested bullets/hierarchies; no ANSI codes; don't cram unrelated keywords; keep keyword lists short—wrap/reformat if long; avoid naming formatting styles in answers.
|
||||
- Adaptation: code explanations → precise, structured with code refs; simple tasks → lead with outcome; big changes → logical walkthrough + rationale + next actions; casual one-offs → plain sentences, no headers/bullets.
|
||||
- File References: When referencing files in your response follow the below rules:
|
||||
* Use inline code to make file paths clickable.
|
||||
* Each reference should have a stand alone path. Even if it's the same file.
|
||||
* Accepted: absolute, workspace‑relative, a/ or b/ diff prefixes, or bare filename/suffix.
|
||||
* Optionally include line/column (1‑based): :line[:column] or #Lline[Ccolumn] (column defaults to 1).
|
||||
* Do not use URIs like file://, vscode://, or https://.
|
||||
* Do not provide range of lines
|
||||
* Examples: src/app.ts, src/app.ts:42, b/server/index.js#L10, C:\\repo\\project\\main.rs:12:5`;
|
||||
175
open-sse/config/constants.ts
Normal file
175
open-sse/config/constants.ts
Normal file
@@ -0,0 +1,175 @@
|
||||
import { loadProviderCredentials } from "./credentialLoader.ts";
|
||||
|
||||
// Timeout for non-streaming fetch requests (ms). Prevents stalled connections.
|
||||
export const FETCH_TIMEOUT_MS = parseInt(process.env.FETCH_TIMEOUT_MS || "120000", 10);
|
||||
|
||||
// Idle timeout for SSE streams (ms). Closes stream if no data for this duration.
|
||||
export const STREAM_IDLE_TIMEOUT_MS = parseInt(process.env.STREAM_IDLE_TIMEOUT_MS || "60000", 10);
|
||||
|
||||
// Provider configurations
|
||||
// OAuth credentials read from env vars with hardcoded fallbacks for backward compatibility.
|
||||
// Use provider-credentials.json or env vars to override in production.
|
||||
import { generateLegacyProviders } from "./providerRegistry.ts";
|
||||
|
||||
export const PROVIDERS = generateLegacyProviders();
|
||||
|
||||
// Merge external credentials from data/provider-credentials.json (if present)
|
||||
loadProviderCredentials(PROVIDERS);
|
||||
|
||||
// Claude system prompt
|
||||
export const CLAUDE_SYSTEM_PROMPT = "You are Claude Code, Anthropic's official CLI for Claude.";
|
||||
|
||||
// Antigravity default system prompt (required for API to work)
|
||||
export const ANTIGRAVITY_DEFAULT_SYSTEM =
|
||||
"Please ignore the following [ignore]You are Antigravity, a powerful agentic AI coding assistant designed by the Google Deepmind team working on Advanced Agentic Coding.You are pair programming with a USER to solve their coding task. The task may require creating a new codebase, modifying or debugging an existing codebase, or simply answering a question.**Absolute paths only****Proactiveness**[/ignore]";
|
||||
|
||||
// OAuth endpoints
|
||||
export const OAUTH_ENDPOINTS = {
|
||||
google: {
|
||||
token: "https://oauth2.googleapis.com/token",
|
||||
auth: "https://accounts.google.com/o/oauth2/auth",
|
||||
},
|
||||
openai: {
|
||||
token: "https://auth.openai.com/oauth/token",
|
||||
auth: "https://auth.openai.com/oauth/authorize",
|
||||
},
|
||||
anthropic: {
|
||||
token: "https://console.anthropic.com/v1/oauth/token",
|
||||
auth: "https://console.anthropic.com/v1/oauth/authorize",
|
||||
},
|
||||
qwen: {
|
||||
token: "https://chat.qwen.ai/api/v1/oauth2/token", // From CLIProxyAPI
|
||||
auth: "https://chat.qwen.ai/api/v1/oauth2/device/code", // From CLIProxyAPI
|
||||
},
|
||||
iflow: {
|
||||
token: "https://iflow.cn/oauth/token",
|
||||
auth: "https://iflow.cn/oauth",
|
||||
},
|
||||
github: {
|
||||
token: "https://github.com/login/oauth/access_token",
|
||||
auth: "https://github.com/login/oauth/authorize",
|
||||
deviceCode: "https://github.com/login/device/code",
|
||||
},
|
||||
};
|
||||
|
||||
// Cache TTLs (seconds)
|
||||
export const CACHE_TTL = {
|
||||
userInfo: 300, // 5 minutes
|
||||
modelAlias: 3600, // 1 hour
|
||||
};
|
||||
|
||||
// Default max tokens
|
||||
export const DEFAULT_MAX_TOKENS = 64000;
|
||||
|
||||
// Minimum max tokens for tool calling (to prevent truncated arguments)
|
||||
export const DEFAULT_MIN_TOKENS = 32000;
|
||||
|
||||
// HTTP status codes
|
||||
export const HTTP_STATUS = {
|
||||
BAD_REQUEST: 400,
|
||||
UNAUTHORIZED: 401,
|
||||
PAYMENT_REQUIRED: 402,
|
||||
FORBIDDEN: 403,
|
||||
NOT_FOUND: 404,
|
||||
NOT_ACCEPTABLE: 406,
|
||||
REQUEST_TIMEOUT: 408,
|
||||
RATE_LIMITED: 429,
|
||||
SERVER_ERROR: 500,
|
||||
BAD_GATEWAY: 502,
|
||||
SERVICE_UNAVAILABLE: 503,
|
||||
GATEWAY_TIMEOUT: 504,
|
||||
};
|
||||
|
||||
// OpenAI-compatible error types mapping
|
||||
export const ERROR_TYPES = {
|
||||
[HTTP_STATUS.BAD_REQUEST]: { type: "invalid_request_error", code: "bad_request" },
|
||||
[HTTP_STATUS.UNAUTHORIZED]: { type: "authentication_error", code: "invalid_api_key" },
|
||||
[HTTP_STATUS.FORBIDDEN]: { type: "permission_error", code: "insufficient_quota" },
|
||||
[HTTP_STATUS.NOT_FOUND]: { type: "invalid_request_error", code: "model_not_found" },
|
||||
[HTTP_STATUS.RATE_LIMITED]: { type: "rate_limit_error", code: "rate_limit_exceeded" },
|
||||
[HTTP_STATUS.SERVER_ERROR]: { type: "server_error", code: "internal_server_error" },
|
||||
[HTTP_STATUS.BAD_GATEWAY]: { type: "server_error", code: "bad_gateway" },
|
||||
[HTTP_STATUS.SERVICE_UNAVAILABLE]: { type: "server_error", code: "service_unavailable" },
|
||||
[HTTP_STATUS.GATEWAY_TIMEOUT]: { type: "server_error", code: "gateway_timeout" },
|
||||
};
|
||||
|
||||
// Default error messages per status code
|
||||
export const DEFAULT_ERROR_MESSAGES = {
|
||||
[HTTP_STATUS.BAD_REQUEST]: "Bad request",
|
||||
[HTTP_STATUS.UNAUTHORIZED]: "Invalid API key provided",
|
||||
[HTTP_STATUS.FORBIDDEN]: "You exceeded your current quota",
|
||||
[HTTP_STATUS.NOT_FOUND]: "Model not found",
|
||||
[HTTP_STATUS.RATE_LIMITED]: "Rate limit exceeded",
|
||||
[HTTP_STATUS.SERVER_ERROR]: "Internal server error",
|
||||
[HTTP_STATUS.BAD_GATEWAY]: "Bad gateway - upstream provider error",
|
||||
[HTTP_STATUS.SERVICE_UNAVAILABLE]: "Service temporarily unavailable",
|
||||
[HTTP_STATUS.GATEWAY_TIMEOUT]: "Gateway timeout",
|
||||
};
|
||||
|
||||
// Exponential backoff config for rate limits (like CLIProxyAPI)
|
||||
export const BACKOFF_CONFIG = {
|
||||
base: 1000, // 1 second base
|
||||
max: 2 * 60 * 1000, // 2 minutes max
|
||||
maxLevel: 15, // Cap backoff level
|
||||
};
|
||||
|
||||
// Configurable backoff steps for rate limits (Phase 1 — enhanced rate limiting)
|
||||
// Used for per-model lockouts with increasing severity
|
||||
export const BACKOFF_STEPS_MS = [60_000, 120_000, 300_000, 600_000, 1_200_000];
|
||||
// 1min → 2min → 5min → 10min → 20min
|
||||
|
||||
// Structured error classification for rate limiting decisions
|
||||
export const RateLimitReason = {
|
||||
QUOTA_EXHAUSTED: "quota_exhausted", // Daily/monthly quota depleted
|
||||
RATE_LIMIT_EXCEEDED: "rate_limit_exceeded", // RPM/RPD limits hit
|
||||
MODEL_CAPACITY: "model_capacity", // Model overloaded (529, 503)
|
||||
SERVER_ERROR: "server_error", // 5xx errors
|
||||
AUTH_ERROR: "auth_error", // 401, 403
|
||||
UNKNOWN: "unknown",
|
||||
};
|
||||
|
||||
// Error-based cooldown times (aligned with CLIProxyAPI)
|
||||
export const COOLDOWN_MS = {
|
||||
unauthorized: 2 * 60 * 1000, // 401 → 2 min
|
||||
paymentRequired: 2 * 60 * 1000, // 402/403 → 2 min
|
||||
notFound: 2 * 60 * 1000, // 404 → 2 minutes
|
||||
transientInitial: 5 * 1000, // 408/500/502/503/504 first hit → 5s (backoff from here)
|
||||
transientMax: 60 * 1000, // 502/503/504 backoff ceiling → 60s
|
||||
transient: 5 * 1000, // Legacy alias → points to transientInitial
|
||||
requestNotAllowed: 5 * 1000, // "Request not allowed" → 5 sec
|
||||
// Legacy aliases for backward compatibility
|
||||
rateLimit: 2 * 60 * 1000,
|
||||
serviceUnavailable: 2 * 1000,
|
||||
authExpired: 2 * 60 * 1000,
|
||||
};
|
||||
|
||||
// ─── Provider Resilience Profiles ───────────────────────────────────────────
|
||||
// Separate behavior for OAuth (low-limit, session-based) vs API Key (high-limit, metered)
|
||||
export const PROVIDER_PROFILES = {
|
||||
oauth: {
|
||||
transientCooldown: 5000, // 5s (session tokens — short recovery)
|
||||
rateLimitCooldown: 60000, // 60s default when no retry-after header
|
||||
maxBackoffLevel: 8, // Higher ceiling (sessions may stay bad longer)
|
||||
circuitBreakerThreshold: 3, // Opens fast (low limit providers)
|
||||
circuitBreakerReset: 60000, // 1min reset
|
||||
},
|
||||
apikey: {
|
||||
transientCooldown: 3000, // 3s (API providers recover faster)
|
||||
rateLimitCooldown: 0, // 0 = respect retry-after header from provider
|
||||
maxBackoffLevel: 5, // Lower ceiling (API quotas reset at known intervals)
|
||||
circuitBreakerThreshold: 5, // More tolerant (occasional 502 is normal)
|
||||
circuitBreakerReset: 30000, // 30s reset
|
||||
},
|
||||
};
|
||||
|
||||
// Default rate limit values for API Key providers (auto-enabled safety net)
|
||||
// These are intentionally HIGH — they won't restrict normal usage.
|
||||
// Real limits are learned from provider response headers.
|
||||
export const DEFAULT_API_LIMITS = {
|
||||
requestsPerMinute: 100, // 100 RPM (most APIs allow 60-600 RPM)
|
||||
minTimeBetweenRequests: 200, // 200ms minimum gap
|
||||
concurrentRequests: 10, // Max 10 parallel per provider
|
||||
};
|
||||
|
||||
// Skip patterns - requests containing these texts will bypass provider
|
||||
export const SKIP_PATTERNS = ["Please write a 5-10 word title for the following conversation:"];
|
||||
102
open-sse/config/credentialLoader.ts
Normal file
102
open-sse/config/credentialLoader.ts
Normal file
@@ -0,0 +1,102 @@
|
||||
/**
|
||||
* Credential Loader — Reads provider credentials from an external JSON file.
|
||||
*
|
||||
* Loads `provider-credentials.json` from the data directory and merges it
|
||||
* over the hardcoded defaults in PROVIDERS. This keeps credentials out of
|
||||
* source control while maintaining backwards compatibility (hardcoded values
|
||||
* serve as defaults when the file is absent).
|
||||
*
|
||||
* Expected JSON structure:
|
||||
* {
|
||||
* "claude": { "clientId": "..." },
|
||||
* "gemini": { "clientId": "...", "clientSecret": "..." },
|
||||
* ...
|
||||
* }
|
||||
*/
|
||||
|
||||
import { readFileSync, existsSync } from "fs";
|
||||
import { join } from "path";
|
||||
|
||||
// Fields that can be overridden per provider
|
||||
const CREDENTIAL_FIELDS = ["clientId", "clientSecret", "tokenUrl", "authUrl", "refreshUrl"];
|
||||
|
||||
// TTL-based cache — reloads credentials from disk at most once per minute
|
||||
const CONFIG_TTL_MS = 60_000;
|
||||
let lastLoadTime = 0;
|
||||
let cachedProviders = null;
|
||||
|
||||
/**
|
||||
* Resolve the path to provider-credentials.json
|
||||
* Priority: DATA_DIR env → ./data (project root)
|
||||
*/
|
||||
function resolveCredentialsPath() {
|
||||
const dataDir = process.env.DATA_DIR || join(process.cwd(), "data");
|
||||
return join(dataDir, "provider-credentials.json");
|
||||
}
|
||||
|
||||
/**
|
||||
* Load and merge external credentials into the PROVIDERS object.
|
||||
* Uses TTL-based caching (60s) so credential file changes are picked up
|
||||
* without requiring a server restart.
|
||||
*
|
||||
* @param {object} providers - The PROVIDERS object from constants.js
|
||||
* @returns {object} The same PROVIDERS object (mutated in place)
|
||||
*/
|
||||
export function loadProviderCredentials(providers) {
|
||||
// Return cached result if within TTL
|
||||
if (cachedProviders && Date.now() - lastLoadTime < CONFIG_TTL_MS) {
|
||||
return cachedProviders;
|
||||
}
|
||||
|
||||
const credPath = resolveCredentialsPath();
|
||||
|
||||
if (!existsSync(credPath)) {
|
||||
if (!cachedProviders) {
|
||||
console.log("[CREDENTIALS] No external credentials file found, using defaults.");
|
||||
}
|
||||
cachedProviders = providers;
|
||||
lastLoadTime = Date.now();
|
||||
return providers;
|
||||
}
|
||||
|
||||
try {
|
||||
const raw = readFileSync(credPath, "utf-8");
|
||||
const external = JSON.parse(raw);
|
||||
|
||||
let overrideCount = 0;
|
||||
|
||||
for (const [providerKey, creds] of Object.entries(external)) {
|
||||
if (!providers[providerKey]) {
|
||||
console.log(
|
||||
`[CREDENTIALS] Warning: unknown provider "${providerKey}" in credentials file, skipping.`
|
||||
);
|
||||
continue;
|
||||
}
|
||||
|
||||
if (!creds || typeof creds !== "object") {
|
||||
console.log(
|
||||
`[CREDENTIALS] Warning: provider "${providerKey}" value must be an object, got ${typeof creds}. Skipping.`
|
||||
);
|
||||
continue;
|
||||
}
|
||||
|
||||
for (const field of CREDENTIAL_FIELDS) {
|
||||
if (creds[field] !== undefined) {
|
||||
providers[providerKey][field] = creds[field];
|
||||
overrideCount++;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
const isReload = cachedProviders !== null;
|
||||
console.log(
|
||||
`[CREDENTIALS] ${isReload ? "Reloaded" : "Loaded"} external credentials: ${overrideCount} field(s) from ${credPath}`
|
||||
);
|
||||
} catch (err) {
|
||||
console.log(`[CREDENTIALS] Error reading credentials file: ${err.message}. Using defaults.`);
|
||||
}
|
||||
|
||||
cachedProviders = providers;
|
||||
lastLoadTime = Date.now();
|
||||
return providers;
|
||||
}
|
||||
8
open-sse/config/defaultThinkingSignature.ts
Normal file
8
open-sse/config/defaultThinkingSignature.ts
Normal file
@@ -0,0 +1,8 @@
|
||||
// Default signature for thinking mode when no signature from thinkingStore
|
||||
export const DEFAULT_THINKING_CLAUDE_SIGNATURE =
|
||||
"EpwGCkYIChgCKkCzVUuRrg7CcglSUWEef4rH6o35g9UYS8ZPe0/VomQTBsFx6sttYNj5l8GqgW6ejuHyYqpFToxIbZl0bw17l5dJEgzCnqDO0Z8fRlMrNgsaDLS1cnCjC53KBqE0CCIwAADQdo1eO+7qPAmo8J4WR3JPmr92S97kmvr5K1iPMiOpkZNj8mEXW8uzBoOJs/9ZKoMFiqHJ3UObwaJDqFOW70E9oCwDoc6jesaWVAEdN5vWfKMpIkjFJjECdjIdkxyJNJ8Ib8yXVal3qwE7uThoPRqSZDdHB5mmwPEjWE/90cSYCbtX2YsJki1265CabBb8/QEkODXg4kgRrL+c8e8rRXz/dr1RswvaPuzEdGKHRNi9UooNUeOK4/ebx1KkP9YZttyohN9GWqlts36kOoW0Cfie/ABDgF9g534BPth/sstxDM6d79QlRmh6NxizyTF74DXJI34u0M4tTRchqE5pAq85SgdJaa+dix1yJPMji8m6nZkwJbscJb9rdc2MKyKWjz8QL2+rTSSuZ2F1k1qSsW0xNcI7qLcI12Vncfn/VqY6YOIZy/saZBR0ezXvN6g+UYbuIdyVg7AyIFZt3nbrO7/kmOEb2VKzygwklHGEIJHfFgMpH3JSrAzbZIowVHOF7VaJ+KXRFDCFin7hHTOiOsdg+1ij1mML9Z/x/9CP4b7OUcaQm1llDZPSHc6rZMNL3DdB+fW5YfmNgKU35S+7AMtA10nVILzDAk1UV4T2K9Do09JlI6rjOs9UuULlIN2Z0eE8YTlANR6uQcw7lMcdfqYE8tke4rDKc2dDiaS5vVe45VewICNpdXGN11yw8QqH7p27CR1HtN30e0tHXOR3bIwWk/Yb6O5fTaKG6Ri8e5ZCPvdD9HqepVi188nM0iTjJqL58F3ni04ECIhcbyaQWnuTes1Kw4CMwiZDLQkk8Hgz7HkUOf1btQTF/0nhD7ry0n0hAEg2PaDM3V6TjOjf4hEldRmeqERcQF1PfgKb6ZM12rlIIfUqKACczWJSzTV158+47HX36o0cgux6nFlv/DE+sEiRVxgB";
|
||||
|
||||
export const DEFAULT_THINKING_GEMINI_SIGNATURE =
|
||||
"EuwGCukGAXLI2nxwZIq54WWSoL/YN0P3TsDZ7zRnLi8g0S4aVr2HUGxvaHKySuY6HAVzcE0GPGjXrytLIldxthSvfxgUlJh6Qa9Z+Oj5QZBlYdg6HaJ6yuY5R7waE6rdwBsRf7Ft2j3DJ9rMi9qhWFqApewYtPhls3VHtuvND3l8Rm09+lbAXQs6KKWEWrxNLKTBkfpMgXhRERc/TQRMZu1twAablm6/Zk1tsYRvfWKLsNbeKF+CCojJdXJKvnR/8Ouuoa+Y2Ti20hcW7aZIIjZDFYPU//k6Ybmhg69J/imbFai2ckhfLaisqdDkdoIiBJScTOUvYqP6AE9d4MsydSC+UlhIMk4hoP76R8vUSCZRMkjOaDXstf/QoVZKbt94wyRZgAJ1G0BqI8L5ow86kLpA4wJEtxsRGymOE4bKUvApveBakYDNM9APkf+LbtbzWSseGjoZcSlycF9iN8Q2XNYKRrHbv3Lr5Y8JjdH/5y/6SHkNehTEZugaeGnSPSyCTWto1kQgHpxdWmhkLfJGNUGLmue7Mesj4TSms4J33mRpYVhNB/J333FCqIP0hr/E7BkkjEn7yZ4X7SQlh+xKPurapsnHRwiKmtsilmEFrnTE9iQr+pMr6M29qqFNv1tr5yumbaJw8JW9sB15tNsRv+dW6BjNanbsKz7HCgKUBc8tGy+7YuhXzAfViyRefcjK7eZW0Fbyt7AbybJTKz78W8NH7ye6LAwzOebXpeZ4D43fNIt8bKh26qgduSQv/7o+pAflkuqHZ99YWgHQ8h8OkZFi3eOiSYjsjhdZ/czWOdoPI/OnqIldzMPF5YlrKBLFX8VhRKVmqgsmWf5PHGulHhMkVlS+XG2UIseGy69ARa93D78Gsa+1n1kJr7EEB7Rh+27vUMxVYLdz1yMSvE5nalTAlg/ZeG8+XQ0cHuAI3KbQpHW2Q++RdXfm5JzD5WdJZUU+Zn8t8UUn85BH4RxZLeE0qJikgSsKoYVBc6YhiMjhPgkR95ReimY4Z0xCJdRo1gjexOFeODZMpQF6Yxnoic7IrdgsFA3iePTbFnPp3IAM1fAThWhXJUn3QInUOTd5o1qmTmn6REbL15g/JQNl+dqUoPkhleeb2V3kjqp1okmO3wMZbPknR3S1LZNmlS72/iBQUm+n2b/RCn4PjmM2";
|
||||
|
||||
export const DEFAULT_THINKING_TEXT = "...";
|
||||
126
open-sse/config/embeddingRegistry.ts
Normal file
126
open-sse/config/embeddingRegistry.ts
Normal file
@@ -0,0 +1,126 @@
|
||||
/**
|
||||
* Embedding Provider Registry
|
||||
*
|
||||
* Defines providers that support the /v1/embeddings endpoint.
|
||||
* All providers use the OpenAI-compatible format.
|
||||
*
|
||||
* API keys are stored in the same provider credentials system,
|
||||
* keyed by provider ID (e.g. "nebius", "openai").
|
||||
*/
|
||||
|
||||
export const EMBEDDING_PROVIDERS = {
|
||||
nebius: {
|
||||
id: "nebius",
|
||||
baseUrl: "https://api.tokenfactory.nebius.com/v1/embeddings",
|
||||
authType: "apikey",
|
||||
authHeader: "bearer",
|
||||
models: [{ id: "Qwen/Qwen3-Embedding-8B", name: "Qwen3 Embedding 8B", dimensions: 4096 }],
|
||||
},
|
||||
|
||||
openai: {
|
||||
id: "openai",
|
||||
baseUrl: "https://api.openai.com/v1/embeddings",
|
||||
authType: "apikey",
|
||||
authHeader: "bearer",
|
||||
models: [
|
||||
{ id: "text-embedding-3-small", name: "Text Embedding 3 Small", dimensions: 1536 },
|
||||
{ id: "text-embedding-3-large", name: "Text Embedding 3 Large", dimensions: 3072 },
|
||||
{ id: "text-embedding-ada-002", name: "Text Embedding Ada 002", dimensions: 1536 },
|
||||
],
|
||||
},
|
||||
|
||||
mistral: {
|
||||
id: "mistral",
|
||||
baseUrl: "https://api.mistral.ai/v1/embeddings",
|
||||
authType: "apikey",
|
||||
authHeader: "bearer",
|
||||
models: [{ id: "mistral-embed", name: "Mistral Embed", dimensions: 1024 }],
|
||||
},
|
||||
|
||||
together: {
|
||||
id: "together",
|
||||
baseUrl: "https://api.together.xyz/v1/embeddings",
|
||||
authType: "apikey",
|
||||
authHeader: "bearer",
|
||||
models: [
|
||||
{ id: "BAAI/bge-large-en-v1.5", name: "BGE Large EN v1.5", dimensions: 1024 },
|
||||
{ id: "togethercomputer/m2-bert-80M-8k-retrieval", name: "M2 BERT 80M 8K", dimensions: 768 },
|
||||
],
|
||||
},
|
||||
|
||||
fireworks: {
|
||||
id: "fireworks",
|
||||
baseUrl: "https://api.fireworks.ai/inference/v1/embeddings",
|
||||
authType: "apikey",
|
||||
authHeader: "bearer",
|
||||
models: [
|
||||
{ id: "nomic-ai/nomic-embed-text-v1.5", name: "Nomic Embed Text v1.5", dimensions: 768 },
|
||||
],
|
||||
},
|
||||
|
||||
nvidia: {
|
||||
id: "nvidia",
|
||||
baseUrl: "https://integrate.api.nvidia.com/v1/embeddings",
|
||||
authType: "apikey",
|
||||
authHeader: "bearer",
|
||||
models: [{ id: "nvidia/nv-embedqa-e5-v5", name: "NV EmbedQA E5 v5", dimensions: 1024 }],
|
||||
},
|
||||
};
|
||||
|
||||
/**
|
||||
* Get embedding provider config by ID
|
||||
*/
|
||||
export function getEmbeddingProvider(providerId) {
|
||||
return EMBEDDING_PROVIDERS[providerId] || null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Parse embedding model string (format: "provider/model" or just "model")
|
||||
* Returns { provider, model }
|
||||
*/
|
||||
export function parseEmbeddingModel(modelStr) {
|
||||
if (!modelStr) return { provider: null, model: null };
|
||||
|
||||
// Check for "provider/model" format
|
||||
const slashIdx = modelStr.indexOf("/");
|
||||
if (slashIdx > 0) {
|
||||
// Handle nested model IDs like "nebius/Qwen/Qwen3-Embedding-8B"
|
||||
// Try each provider prefix
|
||||
for (const [providerId, config] of Object.entries(EMBEDDING_PROVIDERS)) {
|
||||
if (modelStr.startsWith(providerId + "/")) {
|
||||
return { provider: providerId, model: modelStr.slice(providerId.length + 1) };
|
||||
}
|
||||
}
|
||||
// Fallback: first segment is provider
|
||||
const provider = modelStr.slice(0, slashIdx);
|
||||
const model = modelStr.slice(slashIdx + 1);
|
||||
return { provider, model };
|
||||
}
|
||||
|
||||
// No provider prefix — search all providers for the model
|
||||
for (const [providerId, config] of Object.entries(EMBEDDING_PROVIDERS)) {
|
||||
if (config.models.some((m) => m.id === modelStr)) {
|
||||
return { provider: providerId, model: modelStr };
|
||||
}
|
||||
}
|
||||
|
||||
return { provider: null, model: modelStr };
|
||||
}
|
||||
|
||||
/**
|
||||
* Get all embedding models as a flat list
|
||||
*/
|
||||
export function getAllEmbeddingModels() {
|
||||
const models = [];
|
||||
for (const [providerId, config] of Object.entries(EMBEDDING_PROVIDERS)) {
|
||||
for (const model of config.models) {
|
||||
models.push({
|
||||
id: `${providerId}/${model.id}`,
|
||||
name: model.name,
|
||||
provider: providerId,
|
||||
dimensions: model.dimensions,
|
||||
});
|
||||
}
|
||||
}
|
||||
return models;
|
||||
}
|
||||
160
open-sse/config/imageRegistry.ts
Normal file
160
open-sse/config/imageRegistry.ts
Normal file
@@ -0,0 +1,160 @@
|
||||
/**
|
||||
* Image Generation Provider Registry
|
||||
*
|
||||
* Defines providers that support the /v1/images/generations endpoint.
|
||||
* Each provider has its own request format and endpoint.
|
||||
*/
|
||||
|
||||
export const IMAGE_PROVIDERS = {
|
||||
openai: {
|
||||
id: "openai",
|
||||
baseUrl: "https://api.openai.com/v1/images/generations",
|
||||
authType: "apikey",
|
||||
authHeader: "bearer",
|
||||
format: "openai", // native OpenAI format
|
||||
models: [
|
||||
{ id: "gpt-image-1", name: "GPT Image 1" },
|
||||
{ id: "dall-e-3", name: "DALL-E 3" },
|
||||
{ id: "dall-e-2", name: "DALL-E 2" },
|
||||
],
|
||||
supportedSizes: ["1024x1024", "1024x1792", "1792x1024", "256x256", "512x512"],
|
||||
},
|
||||
|
||||
xai: {
|
||||
id: "xai",
|
||||
baseUrl: "https://api.x.ai/v1/images/generations",
|
||||
authType: "apikey",
|
||||
authHeader: "bearer",
|
||||
format: "openai",
|
||||
models: [{ id: "grok-2-image-1212", name: "Grok 2 Image" }],
|
||||
supportedSizes: ["1024x1024"],
|
||||
},
|
||||
|
||||
together: {
|
||||
id: "together",
|
||||
baseUrl: "https://api.together.xyz/v1/images/generations",
|
||||
authType: "apikey",
|
||||
authHeader: "bearer",
|
||||
format: "openai",
|
||||
models: [
|
||||
{ id: "black-forest-labs/FLUX.1.1-pro", name: "FLUX 1.1 Pro" },
|
||||
{ id: "black-forest-labs/FLUX.1-schnell-Free", name: "FLUX 1 Schnell (Free)" },
|
||||
{ id: "stabilityai/stable-diffusion-xl-base-1.0", name: "SDXL Base 1.0" },
|
||||
],
|
||||
supportedSizes: ["1024x1024", "512x512"],
|
||||
},
|
||||
|
||||
fireworks: {
|
||||
id: "fireworks",
|
||||
baseUrl: "https://api.fireworks.ai/inference/v1/images/generations",
|
||||
authType: "apikey",
|
||||
authHeader: "bearer",
|
||||
format: "openai",
|
||||
models: [
|
||||
{ id: "accounts/fireworks/models/flux-1-dev-fp8", name: "FLUX 1 Dev FP8" },
|
||||
{ id: "accounts/fireworks/models/stable-diffusion-xl-1024-v1-0", name: "SDXL 1024 v1.0" },
|
||||
],
|
||||
supportedSizes: ["1024x1024", "512x512"],
|
||||
},
|
||||
|
||||
antigravity: {
|
||||
id: "antigravity",
|
||||
baseUrl: "https://generativelanguage.googleapis.com/v1beta/models",
|
||||
authType: "oauth",
|
||||
authHeader: "bearer",
|
||||
format: "gemini-image", // Special format: uses Gemini generateContent API
|
||||
models: [{ id: "gemini-2.5-flash-preview-image-generation", name: "Nano Banana" }],
|
||||
supportedSizes: ["1024x1024"],
|
||||
},
|
||||
|
||||
nebius: {
|
||||
id: "nebius",
|
||||
baseUrl: "https://api.tokenfactory.nebius.com/v1/images/generations",
|
||||
fallbackUrl: "https://api.studio.nebius.com/v1/images/generations",
|
||||
authType: "apikey",
|
||||
authHeader: "bearer",
|
||||
format: "openai",
|
||||
models: [
|
||||
{ id: "black-forest-labs/flux-schnell", name: "FLUX.1 Schnell" },
|
||||
{ id: "black-forest-labs/flux-dev", name: "FLUX.1 Dev" },
|
||||
],
|
||||
supportedSizes: ["1024x1024", "512x512"],
|
||||
},
|
||||
|
||||
hyperbolic: {
|
||||
id: "hyperbolic",
|
||||
baseUrl: "https://api.hyperbolic.xyz/v1/image/generation",
|
||||
authType: "apikey",
|
||||
authHeader: "bearer",
|
||||
format: "hyperbolic", // custom: uses model_name, returns base64 images
|
||||
models: [
|
||||
{ id: "SDXL1.0-base", name: "SDXL 1.0 Base" },
|
||||
{ id: "SD2", name: "Stable Diffusion 2" },
|
||||
{ id: "FLUX.1-dev", name: "FLUX.1 Dev" },
|
||||
],
|
||||
supportedSizes: ["1024x1024", "512x512"],
|
||||
},
|
||||
|
||||
nanobanana: {
|
||||
id: "nanobanana",
|
||||
baseUrl: "https://api.nanobananaapi.ai/api/v1/nanobanana/generate",
|
||||
proUrl: "https://api.nanobananaapi.ai/api/v1/nanobanana/generate-pro",
|
||||
authType: "apikey",
|
||||
authHeader: "bearer",
|
||||
format: "nanobanana", // custom format
|
||||
models: [
|
||||
{ id: "nanobanana-flash", name: "NanoBanana Flash (Gemini 2.5 Flash)" },
|
||||
{ id: "nanobanana-pro", name: "NanoBanana Pro (Gemini 3 Pro)" },
|
||||
],
|
||||
supportedSizes: ["1024x1024"],
|
||||
},
|
||||
};
|
||||
|
||||
/**
|
||||
* Get image provider config by ID
|
||||
*/
|
||||
export function getImageProvider(providerId) {
|
||||
return IMAGE_PROVIDERS[providerId] || null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Parse image model string (format: "provider/model")
|
||||
* Returns { provider, model }
|
||||
*/
|
||||
export function parseImageModel(modelStr) {
|
||||
if (!modelStr) return { provider: null, model: null };
|
||||
|
||||
// Try each provider prefix
|
||||
for (const [providerId, config] of Object.entries(IMAGE_PROVIDERS)) {
|
||||
if (modelStr.startsWith(providerId + "/")) {
|
||||
return { provider: providerId, model: modelStr.slice(providerId.length + 1) };
|
||||
}
|
||||
}
|
||||
|
||||
// No provider prefix — try to find the model in any provider
|
||||
for (const [providerId, config] of Object.entries(IMAGE_PROVIDERS)) {
|
||||
if (config.models.some((m) => m.id === modelStr)) {
|
||||
return { provider: providerId, model: modelStr };
|
||||
}
|
||||
}
|
||||
|
||||
return { provider: null, model: modelStr };
|
||||
}
|
||||
|
||||
/**
|
||||
* Get all image models as a flat list
|
||||
*/
|
||||
export function getAllImageModels() {
|
||||
const models = [];
|
||||
for (const [providerId, config] of Object.entries(IMAGE_PROVIDERS)) {
|
||||
for (const model of config.models) {
|
||||
models.push({
|
||||
id: `${providerId}/${model.id}`,
|
||||
name: model.name,
|
||||
provider: providerId,
|
||||
supportedSizes: config.supportedSizes,
|
||||
});
|
||||
}
|
||||
}
|
||||
return models;
|
||||
}
|
||||
64
open-sse/config/moderationRegistry.ts
Normal file
64
open-sse/config/moderationRegistry.ts
Normal file
@@ -0,0 +1,64 @@
|
||||
/**
|
||||
* Moderation Provider Registry
|
||||
*
|
||||
* Defines providers that support the /v1/moderations endpoint.
|
||||
* Follows OpenAI's moderation API format.
|
||||
*/
|
||||
|
||||
export const MODERATION_PROVIDERS = {
|
||||
openai: {
|
||||
id: "openai",
|
||||
baseUrl: "https://api.openai.com/v1/moderations",
|
||||
authType: "apikey",
|
||||
authHeader: "bearer",
|
||||
models: [
|
||||
{ id: "omni-moderation-latest", name: "Omni Moderation Latest" },
|
||||
{ id: "text-moderation-latest", name: "Text Moderation Latest" },
|
||||
],
|
||||
},
|
||||
};
|
||||
|
||||
/**
|
||||
* Get moderation provider config by ID
|
||||
*/
|
||||
export function getModerationProvider(providerId) {
|
||||
return MODERATION_PROVIDERS[providerId] || null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Parse moderation model string
|
||||
*/
|
||||
export function parseModerationModel(modelStr) {
|
||||
if (!modelStr) return { provider: null, model: null };
|
||||
|
||||
for (const [providerId, config] of Object.entries(MODERATION_PROVIDERS)) {
|
||||
if (modelStr.startsWith(providerId + "/")) {
|
||||
return { provider: providerId, model: modelStr.slice(providerId.length + 1) };
|
||||
}
|
||||
}
|
||||
|
||||
for (const [providerId, config] of Object.entries(MODERATION_PROVIDERS)) {
|
||||
if (config.models.some((m) => m.id === modelStr)) {
|
||||
return { provider: providerId, model: modelStr };
|
||||
}
|
||||
}
|
||||
|
||||
return { provider: null, model: modelStr };
|
||||
}
|
||||
|
||||
/**
|
||||
* Get all moderation models as a flat list
|
||||
*/
|
||||
export function getAllModerationModels() {
|
||||
const models = [];
|
||||
for (const [providerId, config] of Object.entries(MODERATION_PROVIDERS)) {
|
||||
for (const model of config.models) {
|
||||
models.push({
|
||||
id: `${providerId}/${model.id}`,
|
||||
name: model.name,
|
||||
provider: providerId,
|
||||
});
|
||||
}
|
||||
}
|
||||
return models;
|
||||
}
|
||||
28
open-sse/config/ollamaModels.ts
Normal file
28
open-sse/config/ollamaModels.ts
Normal file
@@ -0,0 +1,28 @@
|
||||
export const ollamaModels = {
|
||||
models: [
|
||||
{
|
||||
name: "llama3.2",
|
||||
modified_at: "2025-12-26T00:00:00Z",
|
||||
size: 2000000000,
|
||||
digest: "abc123def456",
|
||||
details: {
|
||||
format: "gguf",
|
||||
family: "llama",
|
||||
parameter_size: "3B",
|
||||
quantization_level: "Q4_K_M",
|
||||
},
|
||||
},
|
||||
{
|
||||
name: "qwen2.5",
|
||||
modified_at: "2025-12-26T00:00:00Z",
|
||||
size: 4000000000,
|
||||
digest: "def456abc123",
|
||||
details: {
|
||||
format: "gguf",
|
||||
family: "qwen",
|
||||
parameter_size: "7B",
|
||||
quantization_level: "Q4_K_M",
|
||||
},
|
||||
},
|
||||
],
|
||||
};
|
||||
43
open-sse/config/providerModels.ts
Normal file
43
open-sse/config/providerModels.ts
Normal file
@@ -0,0 +1,43 @@
|
||||
import { generateModels, generateAliasMap } from "./providerRegistry.ts";
|
||||
|
||||
// Provider models - Generated from providerRegistry.js (single source of truth)
|
||||
export const PROVIDER_MODELS = generateModels();
|
||||
|
||||
// Provider ID to alias mapping - Generated from providerRegistry.js
|
||||
export const PROVIDER_ID_TO_ALIAS = generateAliasMap();
|
||||
|
||||
// Helper functions
|
||||
export function getProviderModels(aliasOrId) {
|
||||
return PROVIDER_MODELS[aliasOrId] || [];
|
||||
}
|
||||
|
||||
export function getDefaultModel(aliasOrId) {
|
||||
const models = PROVIDER_MODELS[aliasOrId];
|
||||
return models?.[0]?.id || null;
|
||||
}
|
||||
|
||||
export function isValidModel(aliasOrId, modelId, passthroughProviders = new Set()) {
|
||||
if (passthroughProviders.has(aliasOrId)) return true;
|
||||
const models = PROVIDER_MODELS[aliasOrId];
|
||||
if (!models) return false;
|
||||
return models.some((m) => m.id === modelId);
|
||||
}
|
||||
|
||||
export function findModelName(aliasOrId, modelId) {
|
||||
const models = PROVIDER_MODELS[aliasOrId];
|
||||
if (!models) return modelId;
|
||||
const found = models.find((m) => m.id === modelId);
|
||||
return found?.name || modelId;
|
||||
}
|
||||
|
||||
export function getModelTargetFormat(aliasOrId, modelId) {
|
||||
const models = PROVIDER_MODELS[aliasOrId];
|
||||
if (!models) return null;
|
||||
const found = models.find((m) => m.id === modelId);
|
||||
return found?.targetFormat || null;
|
||||
}
|
||||
|
||||
export function getModelsByProviderId(providerId) {
|
||||
const alias = PROVIDER_ID_TO_ALIAS[providerId] || providerId;
|
||||
return PROVIDER_MODELS[alias] || [];
|
||||
}
|
||||
905
open-sse/config/providerRegistry.ts
Normal file
905
open-sse/config/providerRegistry.ts
Normal file
@@ -0,0 +1,905 @@
|
||||
/**
|
||||
* Provider Registry — Single source of truth for all provider configuration.
|
||||
*
|
||||
* Adding a new provider? Just add an entry here. Everything else
|
||||
* (PROVIDERS, PROVIDER_MODELS, PROVIDER_ID_TO_ALIAS, executor lookup)
|
||||
* is auto-generated from this registry.
|
||||
*/
|
||||
|
||||
// ── Types ─────────────────────────────────────────────────────────────────
|
||||
|
||||
export interface RegistryModel {
|
||||
id: string;
|
||||
name: string;
|
||||
targetFormat?: string;
|
||||
}
|
||||
|
||||
export interface RegistryOAuth {
|
||||
clientIdEnv?: string;
|
||||
clientIdDefault?: string;
|
||||
clientSecretEnv?: string;
|
||||
clientSecretDefault?: string;
|
||||
tokenUrl?: string;
|
||||
refreshUrl?: string;
|
||||
authUrl?: string;
|
||||
initiateUrl?: string;
|
||||
pollUrlBase?: string;
|
||||
}
|
||||
|
||||
export interface RegistryEntry {
|
||||
id: string;
|
||||
alias: string;
|
||||
format: string;
|
||||
executor: string;
|
||||
baseUrl?: string;
|
||||
baseUrls?: string[];
|
||||
responsesBaseUrl?: string;
|
||||
urlSuffix?: string;
|
||||
urlBuilder?: (base: string, model: string, stream: boolean) => string;
|
||||
authType: string;
|
||||
authHeader: string;
|
||||
authPrefix?: string;
|
||||
headers?: Record<string, string>;
|
||||
extraHeaders?: Record<string, string>;
|
||||
oauth?: RegistryOAuth;
|
||||
models: RegistryModel[];
|
||||
chatPath?: string;
|
||||
clientVersion?: string;
|
||||
passthroughModels?: boolean;
|
||||
}
|
||||
|
||||
// ── Registry ──────────────────────────────────────────────────────────────
|
||||
|
||||
export const REGISTRY: Record<string, RegistryEntry> = {
|
||||
// ─── OAuth Providers ───────────────────────────────────────────────────
|
||||
claude: {
|
||||
id: "claude",
|
||||
alias: "cc",
|
||||
format: "claude",
|
||||
executor: "default",
|
||||
baseUrl: "https://api.anthropic.com/v1/messages",
|
||||
urlSuffix: "?beta=true",
|
||||
authType: "oauth",
|
||||
authHeader: "x-api-key",
|
||||
headers: {
|
||||
"Anthropic-Version": "2023-06-01",
|
||||
"Anthropic-Beta":
|
||||
"claude-code-20250219,oauth-2025-04-20,interleaved-thinking-2025-05-14,fine-grained-tool-streaming-2025-05-14,context-management-2025-06-27",
|
||||
"Anthropic-Dangerous-Direct-Browser-Access": "true",
|
||||
"User-Agent": "claude-cli/1.0.83 (external, cli)",
|
||||
"X-App": "cli",
|
||||
"X-Stainless-Helper-Method": "stream",
|
||||
"X-Stainless-Retry-Count": "0",
|
||||
"X-Stainless-Runtime-Version": "v24.3.0",
|
||||
"X-Stainless-Package-Version": "0.55.1",
|
||||
"X-Stainless-Runtime": "node",
|
||||
"X-Stainless-Lang": "js",
|
||||
"X-Stainless-Arch": "arm64",
|
||||
"X-Stainless-Os": "MacOS",
|
||||
"X-Stainless-Timeout": "60",
|
||||
},
|
||||
oauth: {
|
||||
clientIdEnv: "CLAUDE_OAUTH_CLIENT_ID",
|
||||
clientIdDefault: "9d1c250a-e61b-44d9-88ed-5944d1962f5e",
|
||||
tokenUrl: "https://console.anthropic.com/v1/oauth/token",
|
||||
},
|
||||
models: [
|
||||
{ id: "claude-opus-4-6", name: "Claude Opus 4.6" },
|
||||
{ id: "claude-opus-4-5-20251101", name: "Claude 4.5 Opus" },
|
||||
{ id: "claude-sonnet-4-5-20250929", name: "Claude 4.5 Sonnet" },
|
||||
{ id: "claude-haiku-4-5-20251001", name: "Claude 4.5 Haiku" },
|
||||
],
|
||||
},
|
||||
|
||||
gemini: {
|
||||
id: "gemini",
|
||||
alias: "gemini",
|
||||
format: "gemini",
|
||||
executor: "default",
|
||||
baseUrl: "https://generativelanguage.googleapis.com/v1beta/models",
|
||||
urlBuilder: (base, model, stream) => {
|
||||
const action = stream ? "streamGenerateContent?alt=sse" : "generateContent";
|
||||
return `${base}/${model}:${action}`;
|
||||
},
|
||||
authType: "apikey",
|
||||
authHeader: "x-goog-api-key",
|
||||
oauth: {
|
||||
clientIdEnv: "GEMINI_OAUTH_CLIENT_ID",
|
||||
clientIdDefault: "681255809395-oo8ft2oprdrnp9e3aqf6av3hmdib135j.apps.googleusercontent.com",
|
||||
clientSecretEnv: "GEMINI_OAUTH_CLIENT_SECRET",
|
||||
clientSecretDefault: "",
|
||||
},
|
||||
models: [
|
||||
{ id: "gemini-3-pro-preview", name: "Gemini 3 Pro Preview" },
|
||||
{ id: "gemini-2.5-pro", name: "Gemini 2.5 Pro" },
|
||||
{ id: "gemini-2.5-flash", name: "Gemini 2.5 Flash" },
|
||||
{ id: "gemini-2.5-flash-lite", name: "Gemini 2.5 Flash Lite" },
|
||||
],
|
||||
},
|
||||
|
||||
"gemini-cli": {
|
||||
id: "gemini-cli",
|
||||
alias: "gc",
|
||||
format: "gemini-cli",
|
||||
executor: "gemini-cli",
|
||||
baseUrl: "https://cloudcode-pa.googleapis.com/v1internal",
|
||||
urlBuilder: (base, model, stream) => {
|
||||
const action = stream ? "streamGenerateContent?alt=sse" : "generateContent";
|
||||
return `${base}:${action}`;
|
||||
},
|
||||
authType: "oauth",
|
||||
authHeader: "bearer",
|
||||
oauth: {
|
||||
clientIdEnv: "GEMINI_CLI_OAUTH_CLIENT_ID",
|
||||
clientIdDefault: "681255809395-oo8ft2oprdrnp9e3aqf6av3hmdib135j.apps.googleusercontent.com",
|
||||
clientSecretEnv: "GEMINI_CLI_OAUTH_CLIENT_SECRET",
|
||||
clientSecretDefault: "",
|
||||
},
|
||||
models: [
|
||||
{ id: "gemini-3-flash-preview", name: "Gemini 3 Flash Preview" },
|
||||
{ id: "gemini-3-pro-preview", name: "Gemini 3 Pro Preview" },
|
||||
{ id: "gemini-2.5-pro", name: "Gemini 2.5 Pro" },
|
||||
{ id: "gemini-2.5-flash", name: "Gemini 2.5 Flash" },
|
||||
{ id: "gemini-2.5-flash-lite", name: "Gemini 2.5 Flash Lite" },
|
||||
],
|
||||
},
|
||||
|
||||
codex: {
|
||||
id: "codex",
|
||||
alias: "cx",
|
||||
format: "openai-responses",
|
||||
executor: "codex",
|
||||
baseUrl: "https://chatgpt.com/backend-api/codex/responses",
|
||||
authType: "oauth",
|
||||
authHeader: "bearer",
|
||||
headers: {
|
||||
Version: "0.92.0",
|
||||
"Openai-Beta": "responses=experimental",
|
||||
"User-Agent": "codex-cli/0.92.0 (Windows 10.0.26100; x64)",
|
||||
},
|
||||
oauth: {
|
||||
clientIdEnv: "CODEX_OAUTH_CLIENT_ID",
|
||||
clientIdDefault: "app_EMoamEEZ73f0CkXaXp7hrann",
|
||||
clientSecretEnv: "CODEX_OAUTH_CLIENT_SECRET",
|
||||
clientSecretDefault: "",
|
||||
tokenUrl: "https://auth.openai.com/oauth/token",
|
||||
},
|
||||
models: [
|
||||
{ id: "gpt-5.3-codex", name: "GPT 5.3 Codex" },
|
||||
{ id: "gpt-5.3-codex-xhigh", name: "GPT 5.3 Codex (xHigh)" },
|
||||
{ id: "gpt-5.3-codex-high", name: "GPT 5.3 Codex (High)" },
|
||||
{ id: "gpt-5.3-codex-low", name: "GPT 5.3 Codex (Low)" },
|
||||
{ id: "gpt-5.3-codex-none", name: "GPT 5.3 Codex (None)" },
|
||||
{ id: "gpt-5.1-codex-mini", name: "GPT 5.1 Codex Mini" },
|
||||
{ id: "gpt-5.1-codex-mini-high", name: "GPT 5.1 Codex Mini (High)" },
|
||||
{ id: "gpt-5.2-codex", name: "GPT 5.2 Codex" },
|
||||
{ id: "gpt-5.2", name: "GPT 5.2" },
|
||||
{ id: "gpt-5.1-codex-max", name: "GPT 5.1 Codex Max" },
|
||||
{ id: "gpt-5.1-codex", name: "GPT 5.1 Codex" },
|
||||
{ id: "gpt-5.1", name: "GPT 5.1" },
|
||||
{ id: "gpt-5-codex", name: "GPT 5 Codex" },
|
||||
{ id: "gpt-5-codex-mini", name: "GPT 5 Codex Mini" },
|
||||
],
|
||||
},
|
||||
|
||||
qwen: {
|
||||
id: "qwen",
|
||||
alias: "qw",
|
||||
format: "openai",
|
||||
executor: "default",
|
||||
baseUrl: "https://portal.qwen.ai/v1/chat/completions",
|
||||
authType: "oauth",
|
||||
authHeader: "bearer",
|
||||
headers: {
|
||||
"User-Agent": "google-api-nodejs-client/9.15.1",
|
||||
"X-Goog-Api-Client": "gl-node/22.17.0",
|
||||
},
|
||||
oauth: {
|
||||
clientIdEnv: "QWEN_OAUTH_CLIENT_ID",
|
||||
clientIdDefault: "f0304373b74a44d2b584a3fb70ca9e56",
|
||||
tokenUrl: "https://chat.qwen.ai/api/v1/oauth2/token",
|
||||
authUrl: "https://chat.qwen.ai/api/v1/oauth2/device/code",
|
||||
},
|
||||
models: [
|
||||
{ id: "qwen3-coder-plus", name: "Qwen3 Coder Plus" },
|
||||
{ id: "qwen3-coder-flash", name: "Qwen3 Coder Flash" },
|
||||
{ id: "vision-model", name: "Qwen3 Vision Model" },
|
||||
],
|
||||
},
|
||||
|
||||
iflow: {
|
||||
id: "iflow",
|
||||
alias: "if",
|
||||
format: "openai",
|
||||
executor: "default",
|
||||
baseUrl: "https://apis.iflow.cn/v1/chat/completions",
|
||||
authType: "oauth",
|
||||
authHeader: "bearer",
|
||||
headers: {
|
||||
"User-Agent": "iFlow-Cli",
|
||||
},
|
||||
oauth: {
|
||||
clientIdEnv: "IFLOW_OAUTH_CLIENT_ID",
|
||||
clientIdDefault: "10009311001",
|
||||
clientSecretEnv: "IFLOW_OAUTH_CLIENT_SECRET",
|
||||
clientSecretDefault: "",
|
||||
tokenUrl: "https://iflow.cn/oauth/token",
|
||||
authUrl: "https://iflow.cn/oauth",
|
||||
},
|
||||
models: [
|
||||
{ id: "qwen3-coder-plus", name: "Qwen3 Coder Plus" },
|
||||
{ id: "kimi-k2", name: "Kimi K2" },
|
||||
{ id: "kimi-k2-thinking", name: "Kimi K2 Thinking" },
|
||||
{ id: "kimi-k2.5", name: "Kimi K2.5" },
|
||||
{ id: "deepseek-r1", name: "DeepSeek R1" },
|
||||
{ id: "deepseek-v3.2-chat", name: "DeepSeek V3.2 Chat" },
|
||||
{ id: "deepseek-v3.2-reasoner", name: "DeepSeek V3.2 Reasoner" },
|
||||
{ id: "minimax-m2.1", name: "MiniMax M2.1" },
|
||||
{ id: "glm-4.7", name: "GLM 4.7" },
|
||||
],
|
||||
},
|
||||
|
||||
antigravity: {
|
||||
id: "antigravity",
|
||||
alias: "ag",
|
||||
format: "antigravity",
|
||||
executor: "antigravity",
|
||||
baseUrls: ["https://daily-cloudcode-pa.googleapis.com", "https://cloudcode-pa.googleapis.com"],
|
||||
urlBuilder: (base, model, stream) => {
|
||||
const path = stream
|
||||
? "/v1internal:streamGenerateContent?alt=sse"
|
||||
: "/v1internal:generateContent";
|
||||
return `${base}${path}`;
|
||||
},
|
||||
authType: "oauth",
|
||||
authHeader: "bearer",
|
||||
headers: {
|
||||
"User-Agent": "antigravity/1.104.0 darwin/arm64",
|
||||
},
|
||||
oauth: {
|
||||
clientIdEnv: "ANTIGRAVITY_OAUTH_CLIENT_ID",
|
||||
clientIdDefault: "1071006060591-tmhssin2h21lcre235vtolojh4g403ep.apps.googleusercontent.com",
|
||||
clientSecretEnv: "ANTIGRAVITY_OAUTH_CLIENT_SECRET",
|
||||
clientSecretDefault: "",
|
||||
},
|
||||
models: [
|
||||
{ id: "claude-opus-4-6-thinking", name: "Claude Opus 4.6 Thinking" },
|
||||
{ id: "claude-opus-4-5-thinking", name: "Claude Opus 4.5 Thinking" },
|
||||
{ id: "claude-sonnet-4-5-thinking", name: "Claude Sonnet 4.5 Thinking" },
|
||||
{ id: "claude-sonnet-4-5", name: "Claude Sonnet 4.5" },
|
||||
{ id: "gemini-3-pro-high", name: "Gemini 3 Pro High" },
|
||||
{ id: "gemini-3-pro-low", name: "Gemini 3 Pro Low" },
|
||||
{ id: "gemini-3-flash-preview", name: "Gemini 3 Flash Preview" },
|
||||
{ id: "gemini-3-flash", name: "Gemini 3 Flash" },
|
||||
{ id: "gemini-2.5-flash", name: "Gemini 2.5 Flash" },
|
||||
],
|
||||
},
|
||||
|
||||
github: {
|
||||
id: "github",
|
||||
alias: "gh",
|
||||
format: "openai",
|
||||
executor: "github",
|
||||
baseUrl: "https://api.githubcopilot.com/chat/completions",
|
||||
responsesBaseUrl: "https://api.githubcopilot.com/responses",
|
||||
authType: "oauth",
|
||||
authHeader: "bearer",
|
||||
headers: {
|
||||
"copilot-integration-id": "vscode-chat",
|
||||
"editor-version": "vscode/1.107.1",
|
||||
"editor-plugin-version": "copilot-chat/0.26.7",
|
||||
"user-agent": "GitHubCopilotChat/0.26.7",
|
||||
"openai-intent": "conversation-panel",
|
||||
"x-github-api-version": "2025-04-01",
|
||||
"x-vscode-user-agent-library-version": "electron-fetch",
|
||||
"X-Initiator": "user",
|
||||
Accept: "application/json",
|
||||
"Content-Type": "application/json",
|
||||
},
|
||||
models: [
|
||||
{ id: "gpt-4.1", name: "GPT-4.1" },
|
||||
{ id: "gpt-4o", name: "GPT-4o" },
|
||||
{ id: "gpt-4o-mini", name: "GPT-4o Mini" },
|
||||
{ id: "gpt-4", name: "GPT-4" },
|
||||
{ id: "gpt-3.5-turbo", name: "GPT-3.5 Turbo" },
|
||||
{ id: "gpt-5", name: "GPT-5" },
|
||||
{ id: "gpt-5-mini", name: "GPT-5 Mini" },
|
||||
{ id: "gpt-5-codex", name: "GPT-5 Codex", targetFormat: "openai-responses" },
|
||||
{ id: "gpt-5.1", name: "GPT-5.1" },
|
||||
{ id: "gpt-5.1-codex", name: "GPT-5.1 Codex", targetFormat: "openai-responses" },
|
||||
{ id: "gpt-5.1-codex-mini", name: "GPT-5.1 Codex Mini", targetFormat: "openai-responses" },
|
||||
{ id: "gpt-5.1-codex-max", name: "GPT-5.1 Codex Max", targetFormat: "openai-responses" },
|
||||
{ id: "gpt-5.2", name: "GPT-5.2" },
|
||||
{ id: "gpt-5.2-codex", name: "GPT-5.2 Codex", targetFormat: "openai-responses" },
|
||||
{ id: "claude-haiku-4.5", name: "Claude Haiku 4.5" },
|
||||
{ id: "claude-opus-4.1", name: "Claude Opus 4.1" },
|
||||
{ id: "claude-opus-4.6", name: "Claude Opus 4.6" },
|
||||
{ id: "claude-opus-4-5-20251101", name: "Claude Opus 4.5 (Full ID)" },
|
||||
{ id: "claude-sonnet-4", name: "Claude Sonnet 4" },
|
||||
{ id: "claude-sonnet-4.5", name: "Claude Sonnet 4.5" },
|
||||
{ id: "gemini-2.5-pro", name: "Gemini 2.5 Pro" },
|
||||
{ id: "gemini-3-flash-preview", name: "Gemini 3 Flash Preview" },
|
||||
{ id: "gemini-3-pro-preview", name: "Gemini 3 Pro Preview" },
|
||||
{ id: "grok-code-fast-1", name: "Grok Code Fast 1" },
|
||||
{ id: "oswe-vscode-prime", name: "Raptor Mini" },
|
||||
],
|
||||
},
|
||||
|
||||
kiro: {
|
||||
id: "kiro",
|
||||
alias: "kr",
|
||||
format: "kiro",
|
||||
executor: "kiro",
|
||||
baseUrl: "https://codewhisperer.us-east-1.amazonaws.com/generateAssistantResponse",
|
||||
authType: "oauth",
|
||||
authHeader: "bearer",
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
Accept: "application/vnd.amazon.eventstream",
|
||||
"X-Amz-Target": "AmazonCodeWhispererStreamingService.GenerateAssistantResponse",
|
||||
"User-Agent": "AWS-SDK-JS/3.0.0 kiro-ide/1.0.0",
|
||||
"X-Amz-User-Agent": "aws-sdk-js/3.0.0 kiro-ide/1.0.0",
|
||||
},
|
||||
oauth: {
|
||||
tokenUrl: "https://prod.us-east-1.auth.desktop.kiro.dev/refreshToken",
|
||||
authUrl: "https://prod.us-east-1.auth.desktop.kiro.dev",
|
||||
},
|
||||
models: [
|
||||
{ id: "claude-sonnet-4.5", name: "Claude Sonnet 4.5" },
|
||||
{ id: "claude-haiku-4.5", name: "Claude Haiku 4.5" },
|
||||
],
|
||||
},
|
||||
|
||||
cursor: {
|
||||
id: "cursor",
|
||||
alias: "cu",
|
||||
format: "cursor",
|
||||
executor: "cursor",
|
||||
baseUrl: "https://api2.cursor.sh",
|
||||
chatPath: "/aiserver.v1.ChatService/StreamUnifiedChatWithTools",
|
||||
authType: "oauth",
|
||||
authHeader: "bearer",
|
||||
headers: {
|
||||
"connect-accept-encoding": "gzip",
|
||||
"connect-protocol-version": "1",
|
||||
"Content-Type": "application/connect+proto",
|
||||
"User-Agent": "connect-es/1.6.1",
|
||||
},
|
||||
clientVersion: "1.1.3",
|
||||
models: [
|
||||
{ id: "default", name: "Auto (Server Picks)" },
|
||||
{ id: "claude-4.5-opus-high-thinking", name: "Claude 4.5 Opus High Thinking" },
|
||||
{ id: "claude-4.5-opus-high", name: "Claude 4.5 Opus High" },
|
||||
{ id: "claude-4.5-sonnet-thinking", name: "Claude 4.5 Sonnet Thinking" },
|
||||
{ id: "claude-4.5-sonnet", name: "Claude 4.5 Sonnet" },
|
||||
{ id: "claude-4.5-haiku", name: "Claude 4.5 Haiku" },
|
||||
{ id: "claude-4.5-opus", name: "Claude 4.5 Opus" },
|
||||
{ id: "gpt-5.2-codex", name: "GPT 5.2 Codex" },
|
||||
],
|
||||
},
|
||||
|
||||
// ─── API Key Providers ─────────────────────────────────────────────────
|
||||
openai: {
|
||||
id: "openai",
|
||||
alias: "openai",
|
||||
format: "openai",
|
||||
executor: "default",
|
||||
baseUrl: "https://api.openai.com/v1/chat/completions",
|
||||
authType: "apikey",
|
||||
authHeader: "bearer",
|
||||
models: [
|
||||
{ id: "gpt-4o", name: "GPT-4o" },
|
||||
{ id: "gpt-4o-mini", name: "GPT-4o Mini" },
|
||||
{ id: "gpt-4-turbo", name: "GPT-4 Turbo" },
|
||||
{ id: "o1", name: "O1" },
|
||||
{ id: "o1-mini", name: "O1 Mini" },
|
||||
],
|
||||
},
|
||||
|
||||
anthropic: {
|
||||
id: "anthropic",
|
||||
alias: "anthropic",
|
||||
format: "claude",
|
||||
executor: "default",
|
||||
baseUrl: "https://api.anthropic.com/v1/messages",
|
||||
urlSuffix: "?beta=true",
|
||||
authType: "apikey",
|
||||
authHeader: "x-api-key",
|
||||
headers: {
|
||||
"Anthropic-Version": "2023-06-01",
|
||||
},
|
||||
models: [
|
||||
{ id: "claude-sonnet-4-20250514", name: "Claude Sonnet 4" },
|
||||
{ id: "claude-opus-4-20250514", name: "Claude Opus 4" },
|
||||
{ id: "claude-3-5-sonnet-20241022", name: "Claude 3.5 Sonnet" },
|
||||
],
|
||||
},
|
||||
|
||||
openrouter: {
|
||||
id: "openrouter",
|
||||
alias: "openrouter",
|
||||
format: "openai",
|
||||
executor: "default",
|
||||
baseUrl: "https://openrouter.ai/api/v1/chat/completions",
|
||||
authType: "apikey",
|
||||
authHeader: "bearer",
|
||||
headers: {
|
||||
"HTTP-Referer": "https://endpoint-proxy.local",
|
||||
"X-Title": "Endpoint Proxy",
|
||||
},
|
||||
models: [{ id: "auto", name: "Auto (Best Available)" }],
|
||||
},
|
||||
|
||||
glm: {
|
||||
id: "glm",
|
||||
alias: "glm",
|
||||
format: "claude",
|
||||
executor: "default",
|
||||
baseUrl: "https://api.z.ai/api/anthropic/v1/messages",
|
||||
urlSuffix: "?beta=true",
|
||||
authType: "apikey",
|
||||
authHeader: "x-api-key",
|
||||
headers: {
|
||||
"Anthropic-Version": "2023-06-01",
|
||||
"Anthropic-Beta": "claude-code-20250219,interleaved-thinking-2025-05-14",
|
||||
},
|
||||
models: [
|
||||
{ id: "glm-4.7-flash", name: "GLM 4.7 Flash" },
|
||||
{ id: "glm-4.7", name: "GLM 4.7" },
|
||||
{ id: "glm-4.6v", name: "GLM 4.6V (Vision)" },
|
||||
{ id: "glm-4.6", name: "GLM 4.6" },
|
||||
{ id: "glm-4.5v", name: "GLM 4.5V (Vision)" },
|
||||
{ id: "glm-4.5", name: "GLM 4.5" },
|
||||
{ id: "glm-4.5-air", name: "GLM 4.5 Air" },
|
||||
{ id: "glm-4-32b", name: "GLM 4 32B" },
|
||||
],
|
||||
},
|
||||
|
||||
kimi: {
|
||||
id: "kimi",
|
||||
alias: "kimi",
|
||||
format: "openai",
|
||||
executor: "default",
|
||||
baseUrl: "https://api.moonshot.ai/v1/chat/completions",
|
||||
authType: "apikey",
|
||||
authHeader: "bearer",
|
||||
models: [
|
||||
{ id: "kimi-k2.5", name: "Kimi K2.5" },
|
||||
{ id: "kimi-k2.5-thinking", name: "Kimi K2.5 Thinking" },
|
||||
{ id: "kimi-latest", name: "Kimi Latest" },
|
||||
],
|
||||
},
|
||||
|
||||
"kimi-coding": {
|
||||
id: "kimi-coding",
|
||||
alias: "kmc",
|
||||
format: "claude",
|
||||
executor: "default",
|
||||
baseUrl: "https://api.kimi.com/coding/v1/messages",
|
||||
urlSuffix: "?beta=true",
|
||||
authType: "oauth",
|
||||
authHeader: "x-api-key",
|
||||
headers: {
|
||||
"Anthropic-Version": "2023-06-01",
|
||||
"Anthropic-Beta": "claude-code-20250219,interleaved-thinking-2025-05-14",
|
||||
},
|
||||
oauth: {
|
||||
clientIdEnv: "KIMI_CODING_OAUTH_CLIENT_ID",
|
||||
clientIdDefault: "17e5f671-d194-4dfb-9706-5516cb48c098",
|
||||
tokenUrl: "https://auth.kimi.com/api/oauth/token",
|
||||
refreshUrl: "https://auth.kimi.com/api/oauth/token",
|
||||
authUrl: "https://auth.kimi.com/api/oauth/device_authorization",
|
||||
},
|
||||
models: [
|
||||
{ id: "kimi-k2.5", name: "Kimi K2.5" },
|
||||
{ id: "kimi-k2.5-thinking", name: "Kimi K2.5 Thinking" },
|
||||
{ id: "kimi-latest", name: "Kimi Latest" },
|
||||
],
|
||||
},
|
||||
|
||||
kilocode: {
|
||||
id: "kilocode",
|
||||
alias: "kc",
|
||||
format: "openrouter",
|
||||
executor: "openrouter",
|
||||
baseUrl: "https://api.kilo.ai/api/openrouter/chat/completions",
|
||||
authType: "oauth",
|
||||
authHeader: "Authorization",
|
||||
authPrefix: "Bearer ",
|
||||
oauth: {
|
||||
initiateUrl: "https://api.kilo.ai/api/device-auth/codes",
|
||||
pollUrlBase: "https://api.kilo.ai/api/device-auth/codes",
|
||||
},
|
||||
models: [
|
||||
{ id: "anthropic/claude-sonnet-4-20250514", name: "Claude Sonnet 4" },
|
||||
{ id: "anthropic/claude-opus-4-20250514", name: "Claude Opus 4" },
|
||||
{ id: "google/gemini-2.5-pro", name: "Gemini 2.5 Pro" },
|
||||
{ id: "google/gemini-2.5-flash", name: "Gemini 2.5 Flash" },
|
||||
{ id: "openai/gpt-4.1", name: "GPT-4.1" },
|
||||
{ id: "openai/o3", name: "o3" },
|
||||
{ id: "deepseek/deepseek-chat", name: "DeepSeek Chat" },
|
||||
{ id: "deepseek/deepseek-reasoner", name: "DeepSeek Reasoner" },
|
||||
],
|
||||
passthroughModels: true,
|
||||
},
|
||||
|
||||
cline: {
|
||||
id: "cline",
|
||||
alias: "cl",
|
||||
format: "openai",
|
||||
executor: "openai",
|
||||
baseUrl: "https://api.cline.bot/api/v1/chat/completions",
|
||||
authType: "oauth",
|
||||
authHeader: "Authorization",
|
||||
authPrefix: "Bearer ",
|
||||
oauth: {
|
||||
tokenUrl: "https://api.cline.bot/api/v1/auth/token",
|
||||
refreshUrl: "https://api.cline.bot/api/v1/auth/refresh",
|
||||
authUrl: "https://api.cline.bot/api/v1/auth/authorize",
|
||||
},
|
||||
extraHeaders: {
|
||||
"HTTP-Referer": "https://cline.bot",
|
||||
"X-Title": "Cline",
|
||||
},
|
||||
models: [
|
||||
{ id: "anthropic/claude-sonnet-4-20250514", name: "Claude Sonnet 4" },
|
||||
{ id: "anthropic/claude-opus-4-20250514", name: "Claude Opus 4" },
|
||||
{ id: "google/gemini-2.5-pro", name: "Gemini 2.5 Pro" },
|
||||
{ id: "google/gemini-2.5-flash", name: "Gemini 2.5 Flash" },
|
||||
{ id: "openai/gpt-4.1", name: "GPT-4.1" },
|
||||
{ id: "openai/o3", name: "o3" },
|
||||
{ id: "deepseek/deepseek-chat", name: "DeepSeek Chat" },
|
||||
],
|
||||
passthroughModels: true,
|
||||
},
|
||||
|
||||
minimax: {
|
||||
id: "minimax",
|
||||
alias: "minimax",
|
||||
format: "claude",
|
||||
executor: "default",
|
||||
baseUrl: "https://api.minimax.io/anthropic/v1/messages",
|
||||
urlSuffix: "?beta=true",
|
||||
authType: "apikey",
|
||||
authHeader: "x-api-key",
|
||||
headers: {
|
||||
"Anthropic-Version": "2023-06-01",
|
||||
"Anthropic-Beta": "claude-code-20250219,interleaved-thinking-2025-05-14",
|
||||
},
|
||||
models: [{ id: "MiniMax-M2.1", name: "MiniMax M2.1" }],
|
||||
},
|
||||
|
||||
"minimax-cn": {
|
||||
id: "minimax-cn",
|
||||
alias: "minimax-cn", // unique alias (was colliding with minimax)
|
||||
format: "claude",
|
||||
executor: "default",
|
||||
baseUrl: "https://api.minimaxi.com/anthropic/v1/messages",
|
||||
urlSuffix: "?beta=true",
|
||||
authType: "apikey",
|
||||
authHeader: "x-api-key",
|
||||
headers: {
|
||||
"Anthropic-Version": "2023-06-01",
|
||||
"Anthropic-Beta": "claude-code-20250219,interleaved-thinking-2025-05-14",
|
||||
},
|
||||
models: [
|
||||
// Keep parity with minimax to ensure model discovery works for minimax-cn connections.
|
||||
{ id: "MiniMax-M2.1", name: "MiniMax M2.1" },
|
||||
],
|
||||
},
|
||||
|
||||
deepseek: {
|
||||
id: "deepseek",
|
||||
alias: "ds",
|
||||
format: "openai",
|
||||
executor: "default",
|
||||
baseUrl: "https://api.deepseek.com/v1/chat/completions",
|
||||
authType: "apikey",
|
||||
authHeader: "bearer",
|
||||
models: [
|
||||
{ id: "deepseek-chat", name: "DeepSeek V3.2 Chat" },
|
||||
{ id: "deepseek-reasoner", name: "DeepSeek V3.2 Reasoner" },
|
||||
],
|
||||
},
|
||||
|
||||
groq: {
|
||||
id: "groq",
|
||||
alias: "groq",
|
||||
format: "openai",
|
||||
executor: "default",
|
||||
baseUrl: "https://api.groq.com/openai/v1/chat/completions",
|
||||
authType: "apikey",
|
||||
authHeader: "bearer",
|
||||
models: [
|
||||
{ id: "llama-3.3-70b-versatile", name: "Llama 3.3 70B" },
|
||||
{ id: "meta-llama/llama-4-maverick-17b-128e-instruct", name: "Llama 4 Maverick" },
|
||||
{ id: "qwen/qwen3-32b", name: "Qwen3 32B" },
|
||||
{ id: "openai/gpt-oss-120b", name: "GPT-OSS 120B" },
|
||||
],
|
||||
},
|
||||
|
||||
xai: {
|
||||
id: "xai",
|
||||
alias: "xai",
|
||||
format: "openai",
|
||||
executor: "default",
|
||||
baseUrl: "https://api.x.ai/v1/chat/completions",
|
||||
authType: "apikey",
|
||||
authHeader: "bearer",
|
||||
models: [
|
||||
{ id: "grok-4", name: "Grok 4" },
|
||||
{ id: "grok-4-fast-reasoning", name: "Grok 4 Fast Reasoning" },
|
||||
{ id: "grok-code-fast-1", name: "Grok Code Fast" },
|
||||
{ id: "grok-3", name: "Grok 3" },
|
||||
],
|
||||
},
|
||||
|
||||
mistral: {
|
||||
id: "mistral",
|
||||
alias: "mistral",
|
||||
format: "openai",
|
||||
executor: "default",
|
||||
baseUrl: "https://api.mistral.ai/v1/chat/completions",
|
||||
authType: "apikey",
|
||||
authHeader: "bearer",
|
||||
models: [
|
||||
{ id: "mistral-large-latest", name: "Mistral Large 3" },
|
||||
{ id: "codestral-latest", name: "Codestral" },
|
||||
{ id: "mistral-medium-latest", name: "Mistral Medium 3" },
|
||||
],
|
||||
},
|
||||
|
||||
perplexity: {
|
||||
id: "perplexity",
|
||||
alias: "pplx",
|
||||
format: "openai",
|
||||
executor: "default",
|
||||
baseUrl: "https://api.perplexity.ai/chat/completions",
|
||||
authType: "apikey",
|
||||
authHeader: "bearer",
|
||||
models: [
|
||||
{ id: "sonar-pro", name: "Sonar Pro" },
|
||||
{ id: "sonar", name: "Sonar" },
|
||||
],
|
||||
},
|
||||
|
||||
together: {
|
||||
id: "together",
|
||||
alias: "together",
|
||||
format: "openai",
|
||||
executor: "default",
|
||||
baseUrl: "https://api.together.xyz/v1/chat/completions",
|
||||
authType: "apikey",
|
||||
authHeader: "bearer",
|
||||
models: [
|
||||
{ id: "meta-llama/Llama-3.3-70B-Instruct-Turbo", name: "Llama 3.3 70B Turbo" },
|
||||
{ id: "deepseek-ai/DeepSeek-R1", name: "DeepSeek R1" },
|
||||
{ id: "Qwen/Qwen3-235B-A22B", name: "Qwen3 235B" },
|
||||
{ id: "meta-llama/Llama-4-Maverick-17B-128E-Instruct-FP8", name: "Llama 4 Maverick" },
|
||||
],
|
||||
},
|
||||
|
||||
fireworks: {
|
||||
id: "fireworks",
|
||||
alias: "fireworks",
|
||||
format: "openai",
|
||||
executor: "default",
|
||||
baseUrl: "https://api.fireworks.ai/inference/v1/chat/completions",
|
||||
authType: "apikey",
|
||||
authHeader: "bearer",
|
||||
models: [
|
||||
{ id: "accounts/fireworks/models/deepseek-v3p1", name: "DeepSeek V3.1" },
|
||||
{ id: "accounts/fireworks/models/llama-v3p3-70b-instruct", name: "Llama 3.3 70B" },
|
||||
{ id: "accounts/fireworks/models/qwen3-235b-a22b", name: "Qwen3 235B" },
|
||||
],
|
||||
},
|
||||
|
||||
cerebras: {
|
||||
id: "cerebras",
|
||||
alias: "cerebras",
|
||||
format: "openai",
|
||||
executor: "default",
|
||||
baseUrl: "https://api.cerebras.ai/v1/chat/completions",
|
||||
authType: "apikey",
|
||||
authHeader: "bearer",
|
||||
models: [
|
||||
{ id: "gpt-oss-120b", name: "GPT OSS 120B" },
|
||||
{ id: "zai-glm-4.7", name: "ZAI GLM 4.7" },
|
||||
{ id: "llama-3.3-70b", name: "Llama 3.3 70B" },
|
||||
{ id: "llama-4-scout-17b-16e-instruct", name: "Llama 4 Scout" },
|
||||
{ id: "qwen-3-235b-a22b-instruct-2507", name: "Qwen3 235B A22B" },
|
||||
{ id: "qwen-3-32b", name: "Qwen3 32B" },
|
||||
],
|
||||
},
|
||||
|
||||
cohere: {
|
||||
id: "cohere",
|
||||
alias: "cohere",
|
||||
format: "openai",
|
||||
executor: "default",
|
||||
baseUrl: "https://api.cohere.com/v2/chat",
|
||||
authType: "apikey",
|
||||
authHeader: "bearer",
|
||||
models: [
|
||||
{ id: "command-r-plus-08-2024", name: "Command R+ (Aug 2024)" },
|
||||
{ id: "command-r-08-2024", name: "Command R (Aug 2024)" },
|
||||
{ id: "command-a-03-2025", name: "Command A (Mar 2025)" },
|
||||
],
|
||||
},
|
||||
|
||||
nvidia: {
|
||||
id: "nvidia",
|
||||
alias: "nvidia",
|
||||
format: "openai",
|
||||
executor: "default",
|
||||
baseUrl: "https://integrate.api.nvidia.com/v1/chat/completions",
|
||||
authType: "apikey",
|
||||
authHeader: "bearer",
|
||||
models: [
|
||||
{ id: "moonshotai/kimi-k2.5", name: "Kimi K2.5" },
|
||||
{ id: "z-ai/glm4.7", name: "GLM 4.7" },
|
||||
{ id: "deepseek-ai/deepseek-v3.2", name: "DeepSeek V3.2" },
|
||||
{ id: "nvidia/llama-3.3-70b-instruct", name: "Llama 3.3 70B" },
|
||||
{ id: "meta/llama-4-maverick-17b-128e-instruct", name: "Llama 4 Maverick" },
|
||||
{ id: "deepseek/deepseek-r1", name: "DeepSeek R1" },
|
||||
],
|
||||
},
|
||||
|
||||
nebius: {
|
||||
id: "nebius",
|
||||
alias: "nebius",
|
||||
format: "openai",
|
||||
executor: "default",
|
||||
baseUrl: "https://api.tokenfactory.nebius.com/v1/chat/completions",
|
||||
authType: "apikey",
|
||||
authHeader: "bearer",
|
||||
models: [{ id: "meta-llama/Llama-3.3-70B-Instruct", name: "Llama 3.3 70B Instruct" }],
|
||||
},
|
||||
|
||||
siliconflow: {
|
||||
id: "siliconflow",
|
||||
alias: "siliconflow",
|
||||
format: "openai",
|
||||
executor: "default",
|
||||
baseUrl: "https://api.siliconflow.com/v1/chat/completions",
|
||||
authType: "apikey",
|
||||
authHeader: "bearer",
|
||||
models: [
|
||||
{ id: "deepseek-ai/DeepSeek-V3.2", name: "DeepSeek V3.2" },
|
||||
{ id: "deepseek-ai/DeepSeek-V3.1", name: "DeepSeek V3.1" },
|
||||
{ id: "deepseek-ai/DeepSeek-R1", name: "DeepSeek R1" },
|
||||
{ id: "Qwen/Qwen3-235B-A22B-Instruct-2507", name: "Qwen3 235B" },
|
||||
{ id: "Qwen/Qwen3-Coder-480B-A35B-Instruct", name: "Qwen3 Coder 480B" },
|
||||
{ id: "Qwen/Qwen3-32B", name: "Qwen3 32B" },
|
||||
{ id: "moonshotai/Kimi-K2.5", name: "Kimi K2.5" },
|
||||
{ id: "zai-org/GLM-4.7", name: "GLM 4.7" },
|
||||
{ id: "openai/gpt-oss-120b", name: "GPT OSS 120B" },
|
||||
{ id: "baidu/ERNIE-4.5-300B-A47B", name: "ERNIE 4.5 300B" },
|
||||
],
|
||||
},
|
||||
|
||||
hyperbolic: {
|
||||
id: "hyperbolic",
|
||||
alias: "hyp",
|
||||
format: "openai",
|
||||
executor: "default",
|
||||
baseUrl: "https://api.hyperbolic.xyz/v1/chat/completions",
|
||||
authType: "apikey",
|
||||
authHeader: "bearer",
|
||||
models: [
|
||||
{ id: "Qwen/QwQ-32B", name: "QwQ 32B" },
|
||||
{ id: "deepseek-ai/DeepSeek-R1", name: "DeepSeek R1" },
|
||||
{ id: "deepseek-ai/DeepSeek-V3", name: "DeepSeek V3" },
|
||||
{ id: "meta-llama/Llama-3.3-70B-Instruct", name: "Llama 3.3 70B" },
|
||||
{ id: "meta-llama/Llama-3.2-3B-Instruct", name: "Llama 3.2 3B" },
|
||||
{ id: "Qwen/Qwen2.5-72B-Instruct", name: "Qwen 2.5 72B" },
|
||||
{ id: "Qwen/Qwen2.5-Coder-32B-Instruct", name: "Qwen 2.5 Coder 32B" },
|
||||
{ id: "NousResearch/Hermes-3-Llama-3.1-70B", name: "Hermes 3 70B" },
|
||||
],
|
||||
},
|
||||
};
|
||||
|
||||
// ── Generator Functions ───────────────────────────────────────────────────
|
||||
|
||||
/** Generate legacy PROVIDERS object shape for constants.js backward compatibility */
|
||||
export function generateLegacyProviders(): Record<string, any> {
|
||||
const providers: Record<string, any> = {};
|
||||
for (const [id, entry] of Object.entries(REGISTRY)) {
|
||||
const p: Record<string, any> = { format: entry.format };
|
||||
|
||||
// URL(s)
|
||||
if (entry.baseUrls) {
|
||||
p.baseUrls = entry.baseUrls;
|
||||
} else if (entry.baseUrl) {
|
||||
p.baseUrl = entry.baseUrl;
|
||||
}
|
||||
if (entry.responsesBaseUrl) {
|
||||
p.responsesBaseUrl = entry.responsesBaseUrl;
|
||||
}
|
||||
|
||||
// Headers
|
||||
const mergedHeaders = {
|
||||
...(entry.headers || {}),
|
||||
...(entry.extraHeaders || {}),
|
||||
};
|
||||
if (Object.keys(mergedHeaders).length > 0) {
|
||||
p.headers = mergedHeaders;
|
||||
}
|
||||
|
||||
// OAuth
|
||||
if (entry.oauth) {
|
||||
if (entry.oauth.clientIdEnv) {
|
||||
p.clientId = process.env[entry.oauth.clientIdEnv] || entry.oauth.clientIdDefault;
|
||||
}
|
||||
if (entry.oauth.clientSecretEnv) {
|
||||
p.clientSecret =
|
||||
process.env[entry.oauth.clientSecretEnv] || entry.oauth.clientSecretDefault;
|
||||
}
|
||||
if (entry.oauth.tokenUrl) p.tokenUrl = entry.oauth.tokenUrl;
|
||||
if (entry.oauth.refreshUrl) p.refreshUrl = entry.oauth.refreshUrl;
|
||||
if (entry.oauth.authUrl) p.authUrl = entry.oauth.authUrl;
|
||||
}
|
||||
|
||||
// Cursor-specific
|
||||
if (entry.chatPath) p.chatPath = entry.chatPath;
|
||||
if (entry.clientVersion) p.clientVersion = entry.clientVersion;
|
||||
|
||||
providers[id] = p;
|
||||
}
|
||||
return providers;
|
||||
}
|
||||
|
||||
/** Generate PROVIDER_MODELS map (alias → model list) */
|
||||
export function generateModels(): Record<string, RegistryModel[]> {
|
||||
const models: Record<string, RegistryModel[]> = {};
|
||||
for (const entry of Object.values(REGISTRY)) {
|
||||
if (entry.models && entry.models.length > 0) {
|
||||
const key = entry.alias || entry.id;
|
||||
// If alias already exists, don't overwrite (first wins)
|
||||
if (!models[key]) {
|
||||
models[key] = entry.models;
|
||||
}
|
||||
}
|
||||
}
|
||||
return models;
|
||||
}
|
||||
|
||||
/** Generate PROVIDER_ID_TO_ALIAS map */
|
||||
export function generateAliasMap(): Record<string, string> {
|
||||
const map: Record<string, string> = {};
|
||||
for (const entry of Object.values(REGISTRY)) {
|
||||
map[entry.id] = entry.alias || entry.id;
|
||||
}
|
||||
return map;
|
||||
}
|
||||
|
||||
// ── Registry Lookup Helpers ───────────────────────────────────────────────
|
||||
|
||||
const _byAlias = new Map();
|
||||
for (const entry of Object.values(REGISTRY)) {
|
||||
if (entry.alias && entry.alias !== entry.id) {
|
||||
_byAlias.set(entry.alias, entry);
|
||||
}
|
||||
}
|
||||
|
||||
/** Get registry entry by provider ID or alias */
|
||||
export function getRegistryEntry(provider: string): RegistryEntry | null {
|
||||
return REGISTRY[provider] || _byAlias.get(provider) || null;
|
||||
}
|
||||
|
||||
/** Get all registered provider IDs */
|
||||
export function getRegisteredProviders(): string[] {
|
||||
return Object.keys(REGISTRY);
|
||||
}
|
||||
|
||||
/**
|
||||
* Get provider category: "oauth" or "apikey"
|
||||
* Used by the resilience layer to apply different cooldown/backoff profiles.
|
||||
* @param {string} provider - Provider ID or alias
|
||||
* @returns {"oauth"|"apikey"}
|
||||
*/
|
||||
export function getProviderCategory(provider: string): "oauth" | "apikey" {
|
||||
const entry = getRegistryEntry(provider);
|
||||
if (!entry) return "apikey"; // Safe default for unknown providers
|
||||
return entry.authType === "apikey" ? "apikey" : "oauth";
|
||||
}
|
||||
96
open-sse/config/rerankRegistry.ts
Normal file
96
open-sse/config/rerankRegistry.ts
Normal file
@@ -0,0 +1,96 @@
|
||||
/**
|
||||
* Rerank Provider Registry
|
||||
*
|
||||
* Defines providers that support the /v1/rerank endpoint.
|
||||
* Follows the Cohere rerank API request/response format (industry standard).
|
||||
*
|
||||
* API keys are stored in the same provider credentials system,
|
||||
* keyed by provider ID (e.g. "cohere", "together").
|
||||
*/
|
||||
|
||||
export const RERANK_PROVIDERS = {
|
||||
cohere: {
|
||||
id: "cohere",
|
||||
baseUrl: "https://api.cohere.com/v2/rerank",
|
||||
authType: "apikey",
|
||||
authHeader: "bearer",
|
||||
models: [
|
||||
{ id: "rerank-v3.5", name: "Rerank v3.5" },
|
||||
{ id: "rerank-english-v3.0", name: "Rerank English v3.0" },
|
||||
{ id: "rerank-multilingual-v3.0", name: "Rerank Multilingual v3.0" },
|
||||
],
|
||||
},
|
||||
|
||||
together: {
|
||||
id: "together",
|
||||
baseUrl: "https://api.together.xyz/v1/rerank",
|
||||
authType: "apikey",
|
||||
authHeader: "bearer",
|
||||
models: [{ id: "Salesforce/Llama-Rank-V2", name: "Llama Rank V2" }],
|
||||
},
|
||||
|
||||
nvidia: {
|
||||
id: "nvidia",
|
||||
baseUrl: "https://integrate.api.nvidia.com/v1/ranking",
|
||||
authType: "apikey",
|
||||
authHeader: "bearer",
|
||||
format: "nvidia", // NVIDIA uses slightly different field names
|
||||
models: [{ id: "nvidia/nv-rerankqa-mistral-4b-v3", name: "NV RerankQA Mistral 4B v3" }],
|
||||
},
|
||||
|
||||
fireworks: {
|
||||
id: "fireworks",
|
||||
baseUrl: "https://api.fireworks.ai/inference/v1/rerank",
|
||||
authType: "apikey",
|
||||
authHeader: "bearer",
|
||||
models: [{ id: "accounts/fireworks/models/nomic-rerank-v1", name: "Nomic Rerank v1" }],
|
||||
},
|
||||
};
|
||||
|
||||
/**
|
||||
* Get rerank provider config by ID
|
||||
*/
|
||||
export function getRerankProvider(providerId) {
|
||||
return RERANK_PROVIDERS[providerId] || null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Parse rerank model string (format: "provider/model" or just "model")
|
||||
* Returns { provider, model }
|
||||
*/
|
||||
export function parseRerankModel(modelStr) {
|
||||
if (!modelStr) return { provider: null, model: null };
|
||||
|
||||
// Try each provider prefix
|
||||
for (const [providerId, config] of Object.entries(RERANK_PROVIDERS)) {
|
||||
if (modelStr.startsWith(providerId + "/")) {
|
||||
return { provider: providerId, model: modelStr.slice(providerId.length + 1) };
|
||||
}
|
||||
}
|
||||
|
||||
// No provider prefix — search all providers for the model
|
||||
for (const [providerId, config] of Object.entries(RERANK_PROVIDERS)) {
|
||||
if (config.models.some((m) => m.id === modelStr)) {
|
||||
return { provider: providerId, model: modelStr };
|
||||
}
|
||||
}
|
||||
|
||||
return { provider: null, model: modelStr };
|
||||
}
|
||||
|
||||
/**
|
||||
* Get all rerank models as a flat list
|
||||
*/
|
||||
export function getAllRerankModels() {
|
||||
const models = [];
|
||||
for (const [providerId, config] of Object.entries(RERANK_PROVIDERS)) {
|
||||
for (const model of config.models) {
|
||||
models.push({
|
||||
id: `${providerId}/${model.id}`,
|
||||
name: model.name,
|
||||
provider: providerId,
|
||||
});
|
||||
}
|
||||
}
|
||||
return models;
|
||||
}
|
||||
273
open-sse/executors/antigravity.ts
Normal file
273
open-sse/executors/antigravity.ts
Normal file
@@ -0,0 +1,273 @@
|
||||
import crypto from "crypto";
|
||||
import { BaseExecutor } from "./base.ts";
|
||||
import { PROVIDERS, OAUTH_ENDPOINTS, HTTP_STATUS } from "../config/constants.ts";
|
||||
|
||||
const MAX_RETRY_AFTER_MS = 10000;
|
||||
|
||||
export class AntigravityExecutor extends BaseExecutor {
|
||||
constructor() {
|
||||
super("antigravity", PROVIDERS.antigravity);
|
||||
}
|
||||
|
||||
buildUrl(model, stream, urlIndex = 0) {
|
||||
const baseUrls = this.getBaseUrls();
|
||||
const baseUrl = baseUrls[urlIndex] || baseUrls[0];
|
||||
const action = stream ? "streamGenerateContent?alt=sse" : "generateContent";
|
||||
return `${baseUrl}/v1internal:${action}`;
|
||||
}
|
||||
|
||||
buildHeaders(credentials, stream = true) {
|
||||
return {
|
||||
"Content-Type": "application/json",
|
||||
Authorization: `Bearer ${credentials.accessToken}`,
|
||||
"User-Agent": this.config.headers?.["User-Agent"] || "antigravity/1.104.0 darwin/arm64",
|
||||
"X-OmniRoute-Source": "omniroute",
|
||||
...(stream && { Accept: "text/event-stream" }),
|
||||
};
|
||||
}
|
||||
|
||||
transformRequest(model, body, stream, credentials) {
|
||||
const projectId = credentials?.projectId || this.generateProjectId();
|
||||
|
||||
// Fix contents for Claude models via Antigravity
|
||||
const normalizedContents =
|
||||
body.request?.contents?.map((c) => {
|
||||
let role = c.role;
|
||||
// functionResponse must be role "user" for Claude models
|
||||
if (c.parts?.some((p) => p.functionResponse)) {
|
||||
role = "user";
|
||||
}
|
||||
|
||||
// Strip thought parts (no valid signature -> provider rejects).
|
||||
// Also drop entries that become empty after filtering, which can trigger
|
||||
// 400 invalid argument on Gemini 3 Flash through Antigravity.
|
||||
const parts = c.parts?.filter((p) => !p.thought && !p.thoughtSignature) || [];
|
||||
return { ...c, role, parts };
|
||||
}) || [];
|
||||
|
||||
const contents = normalizedContents.filter((c) =>
|
||||
Array.isArray(c.parts) ? c.parts.length > 0 : true
|
||||
);
|
||||
|
||||
const transformedRequest = {
|
||||
...body.request,
|
||||
...(contents.length > 0 && { contents }),
|
||||
sessionId: body.request?.sessionId || this.generateSessionId(),
|
||||
safetySettings: undefined,
|
||||
toolConfig:
|
||||
body.request?.tools?.length > 0
|
||||
? { functionCallingConfig: { mode: "VALIDATED" } }
|
||||
: body.request?.toolConfig,
|
||||
};
|
||||
|
||||
return {
|
||||
...body,
|
||||
project: projectId,
|
||||
model: model,
|
||||
userAgent: "antigravity",
|
||||
requestType: "agent",
|
||||
requestId: `agent-${crypto.randomUUID()}`,
|
||||
request: transformedRequest,
|
||||
};
|
||||
}
|
||||
|
||||
async refreshCredentials(credentials, log) {
|
||||
if (!credentials.refreshToken) return null;
|
||||
|
||||
try {
|
||||
const response = await fetch(OAUTH_ENDPOINTS.google.token, {
|
||||
method: "POST",
|
||||
headers: {
|
||||
"Content-Type": "application/x-www-form-urlencoded",
|
||||
Accept: "application/json",
|
||||
},
|
||||
body: new URLSearchParams({
|
||||
grant_type: "refresh_token",
|
||||
refresh_token: credentials.refreshToken,
|
||||
client_id: this.config.clientId,
|
||||
client_secret: this.config.clientSecret,
|
||||
}),
|
||||
});
|
||||
|
||||
if (!response.ok) return null;
|
||||
|
||||
const tokens = await response.json();
|
||||
log?.info?.("TOKEN", "Antigravity refreshed");
|
||||
|
||||
return {
|
||||
accessToken: tokens.access_token,
|
||||
refreshToken: tokens.refresh_token || credentials.refreshToken,
|
||||
expiresIn: tokens.expires_in,
|
||||
projectId: credentials.projectId,
|
||||
};
|
||||
} catch (error) {
|
||||
log?.error?.("TOKEN", `Antigravity refresh error: ${error.message}`);
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
generateProjectId() {
|
||||
const adj = ["useful", "bright", "swift", "calm", "bold"][Math.floor(Math.random() * 5)];
|
||||
const noun = ["fuze", "wave", "spark", "flow", "core"][Math.floor(Math.random() * 5)];
|
||||
return `${adj}-${noun}-${crypto.randomUUID().slice(0, 5)}`;
|
||||
}
|
||||
|
||||
generateSessionId() {
|
||||
return `-${Math.floor(Math.random() * 9_000_000_000_000_000_000)}`;
|
||||
}
|
||||
|
||||
parseRetryHeaders(headers) {
|
||||
if (!headers?.get) return null;
|
||||
|
||||
const retryAfter = headers.get("retry-after");
|
||||
if (retryAfter) {
|
||||
const seconds = parseInt(retryAfter, 10);
|
||||
if (!isNaN(seconds) && seconds > 0) return seconds * 1000;
|
||||
|
||||
const date = new Date(retryAfter);
|
||||
if (!isNaN(date.getTime())) {
|
||||
const diff = date.getTime() - Date.now();
|
||||
return diff > 0 ? diff : null;
|
||||
}
|
||||
}
|
||||
|
||||
const resetAfter = headers.get("x-ratelimit-reset-after");
|
||||
if (resetAfter) {
|
||||
const seconds = parseInt(resetAfter, 10);
|
||||
if (!isNaN(seconds) && seconds > 0) return seconds * 1000;
|
||||
}
|
||||
|
||||
const resetTimestamp = headers.get("x-ratelimit-reset");
|
||||
if (resetTimestamp) {
|
||||
const ts = parseInt(resetTimestamp, 10) * 1000;
|
||||
const diff = ts - Date.now();
|
||||
return diff > 0 ? diff : null;
|
||||
}
|
||||
|
||||
return null;
|
||||
}
|
||||
|
||||
// Parse retry time from Antigravity error message body
|
||||
// Format: "Your quota will reset after 2h7m23s" or "1h30m" or "45m" or "30s"
|
||||
parseRetryFromErrorMessage(errorMessage) {
|
||||
if (!errorMessage || typeof errorMessage !== "string") return null;
|
||||
|
||||
const match = errorMessage.match(/reset after (\d+h)?(\d+m)?(\d+s)?/i);
|
||||
if (!match) return null;
|
||||
|
||||
let totalMs = 0;
|
||||
if (match[1]) totalMs += parseInt(match[1]) * 3600 * 1000; // hours
|
||||
if (match[2]) totalMs += parseInt(match[2]) * 60 * 1000; // minutes
|
||||
if (match[3]) totalMs += parseInt(match[3]) * 1000; // seconds
|
||||
|
||||
return totalMs > 0 ? totalMs : null;
|
||||
}
|
||||
|
||||
async execute({ model, body, stream, credentials, signal, log }) {
|
||||
const fallbackCount = this.getFallbackCount();
|
||||
let lastError = null;
|
||||
let lastStatus = 0;
|
||||
const MAX_AUTO_RETRIES = 3;
|
||||
const retryAttemptsByUrl = {}; // Track retry attempts per URL
|
||||
|
||||
for (let urlIndex = 0; urlIndex < fallbackCount; urlIndex++) {
|
||||
const url = this.buildUrl(model, stream, urlIndex);
|
||||
const headers = this.buildHeaders(credentials, stream);
|
||||
const transformedBody = this.transformRequest(model, body, stream, credentials);
|
||||
|
||||
// Initialize retry counter for this URL
|
||||
if (!retryAttemptsByUrl[urlIndex]) {
|
||||
retryAttemptsByUrl[urlIndex] = 0;
|
||||
}
|
||||
|
||||
try {
|
||||
const response = await fetch(url, {
|
||||
method: "POST",
|
||||
headers,
|
||||
body: JSON.stringify(transformedBody),
|
||||
signal,
|
||||
});
|
||||
|
||||
if (
|
||||
response.status === HTTP_STATUS.RATE_LIMITED ||
|
||||
response.status === HTTP_STATUS.SERVICE_UNAVAILABLE
|
||||
) {
|
||||
// Try to get retry time from headers first
|
||||
let retryMs = this.parseRetryHeaders(response.headers);
|
||||
|
||||
// If no retry time in headers, try to parse from error message body
|
||||
if (!retryMs) {
|
||||
try {
|
||||
const errorBody = await response.clone().text();
|
||||
const errorJson = JSON.parse(errorBody);
|
||||
const errorMessage = errorJson?.error?.message || errorJson?.message || "";
|
||||
retryMs = this.parseRetryFromErrorMessage(errorMessage);
|
||||
} catch (e) {
|
||||
// Ignore parse errors, will fall back to exponential backoff
|
||||
}
|
||||
}
|
||||
|
||||
if (retryMs && retryMs <= MAX_RETRY_AFTER_MS) {
|
||||
log?.debug?.(
|
||||
"RETRY",
|
||||
`${response.status} with Retry-After: ${Math.ceil(retryMs / 1000)}s, waiting...`
|
||||
);
|
||||
await new Promise((resolve) => setTimeout(resolve, retryMs));
|
||||
urlIndex--;
|
||||
continue;
|
||||
}
|
||||
|
||||
// Auto retry only for 429 when retryMs is 0 or undefined
|
||||
if (
|
||||
response.status === HTTP_STATUS.RATE_LIMITED &&
|
||||
(!retryMs || retryMs === 0) &&
|
||||
retryAttemptsByUrl[urlIndex] < MAX_AUTO_RETRIES
|
||||
) {
|
||||
retryAttemptsByUrl[urlIndex]++;
|
||||
// Exponential backoff: 2s, 4s, 8s...
|
||||
const backoffMs = Math.min(
|
||||
1000 * 2 ** retryAttemptsByUrl[urlIndex],
|
||||
MAX_RETRY_AFTER_MS
|
||||
);
|
||||
log?.debug?.(
|
||||
"RETRY",
|
||||
`429 auto retry ${retryAttemptsByUrl[urlIndex]}/${MAX_AUTO_RETRIES} after ${backoffMs / 1000}s`
|
||||
);
|
||||
await new Promise((resolve) => setTimeout(resolve, backoffMs));
|
||||
urlIndex--;
|
||||
continue;
|
||||
}
|
||||
|
||||
log?.debug?.(
|
||||
"RETRY",
|
||||
`${response.status}, Retry-After ${retryMs ? `too long (${Math.ceil(retryMs / 1000)}s)` : "missing"}, trying fallback`
|
||||
);
|
||||
lastStatus = response.status;
|
||||
|
||||
if (urlIndex + 1 < fallbackCount) {
|
||||
continue;
|
||||
}
|
||||
}
|
||||
|
||||
if (this.shouldRetry(response.status, urlIndex)) {
|
||||
log?.debug?.("RETRY", `${response.status} on ${url}, trying fallback ${urlIndex + 1}`);
|
||||
lastStatus = response.status;
|
||||
continue;
|
||||
}
|
||||
|
||||
return { response, url, headers, transformedBody };
|
||||
} catch (error) {
|
||||
lastError = error;
|
||||
if (urlIndex + 1 < fallbackCount) {
|
||||
log?.debug?.("RETRY", `Error on ${url}, trying fallback ${urlIndex + 1}`);
|
||||
continue;
|
||||
}
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
|
||||
throw lastError || new Error(`All ${fallbackCount} URLs failed with status ${lastStatus}`);
|
||||
}
|
||||
}
|
||||
|
||||
export default AntigravityExecutor;
|
||||
136
open-sse/executors/base.ts
Normal file
136
open-sse/executors/base.ts
Normal file
@@ -0,0 +1,136 @@
|
||||
import { HTTP_STATUS, FETCH_TIMEOUT_MS } from "../config/constants.ts";
|
||||
|
||||
/**
|
||||
* BaseExecutor - Base class for provider executors.
|
||||
* Implements the Strategy pattern: subclasses override specific methods
|
||||
* (buildUrl, buildHeaders, transformRequest, etc.) for each provider.
|
||||
*/
|
||||
export class BaseExecutor {
|
||||
provider: any;
|
||||
config: any;
|
||||
|
||||
constructor(provider: any, config: any) {
|
||||
this.provider = provider;
|
||||
this.config = config;
|
||||
}
|
||||
|
||||
getProvider() {
|
||||
return this.provider;
|
||||
}
|
||||
|
||||
getBaseUrls() {
|
||||
return this.config.baseUrls || (this.config.baseUrl ? [this.config.baseUrl] : []);
|
||||
}
|
||||
|
||||
getFallbackCount() {
|
||||
return this.getBaseUrls().length || 1;
|
||||
}
|
||||
|
||||
buildUrl(model, stream, urlIndex = 0, credentials = null) {
|
||||
if (this.provider?.startsWith?.("openai-compatible-")) {
|
||||
const baseUrl = credentials?.providerSpecificData?.baseUrl || "https://api.openai.com/v1";
|
||||
const normalized = baseUrl.replace(/\/$/, "");
|
||||
const path = this.provider.includes("responses") ? "/responses" : "/chat/completions";
|
||||
return `${normalized}${path}`;
|
||||
}
|
||||
const baseUrls = this.getBaseUrls();
|
||||
return baseUrls[urlIndex] || baseUrls[0] || this.config.baseUrl;
|
||||
}
|
||||
|
||||
buildHeaders(credentials, stream = true) {
|
||||
const headers = {
|
||||
"Content-Type": "application/json",
|
||||
...this.config.headers,
|
||||
};
|
||||
|
||||
if (credentials.accessToken) {
|
||||
headers["Authorization"] = `Bearer ${credentials.accessToken}`;
|
||||
} else if (credentials.apiKey) {
|
||||
headers["Authorization"] = `Bearer ${credentials.apiKey}`;
|
||||
}
|
||||
|
||||
if (stream) {
|
||||
headers["Accept"] = "text/event-stream";
|
||||
}
|
||||
|
||||
return headers;
|
||||
}
|
||||
|
||||
// Override in subclass for provider-specific transformations
|
||||
transformRequest(model, body, stream, credentials) {
|
||||
return body;
|
||||
}
|
||||
|
||||
shouldRetry(status, urlIndex) {
|
||||
return status === HTTP_STATUS.RATE_LIMITED && urlIndex + 1 < this.getFallbackCount();
|
||||
}
|
||||
|
||||
// Override in subclass for provider-specific refresh
|
||||
async refreshCredentials(credentials, log) {
|
||||
return null;
|
||||
}
|
||||
|
||||
needsRefresh(credentials) {
|
||||
if (!credentials.expiresAt) return false;
|
||||
const expiresAtMs = new Date(credentials.expiresAt).getTime();
|
||||
return expiresAtMs - Date.now() < 5 * 60 * 1000;
|
||||
}
|
||||
|
||||
parseError(response, bodyText) {
|
||||
return { status: response.status, message: bodyText || `HTTP ${response.status}` };
|
||||
}
|
||||
|
||||
async execute({ model, body, stream, credentials, signal, log }) {
|
||||
const fallbackCount = this.getFallbackCount();
|
||||
let lastError = null;
|
||||
let lastStatus = 0;
|
||||
|
||||
for (let urlIndex = 0; urlIndex < fallbackCount; urlIndex++) {
|
||||
const url = this.buildUrl(model, stream, urlIndex, credentials);
|
||||
const headers = this.buildHeaders(credentials, stream);
|
||||
const transformedBody = this.transformRequest(model, body, stream, credentials);
|
||||
|
||||
try {
|
||||
// For non-streaming requests, apply a fetch timeout to prevent stalled connections.
|
||||
// Streaming requests skip the timeout — they use stream idle detection instead.
|
||||
const timeoutSignal = !stream ? AbortSignal.timeout(FETCH_TIMEOUT_MS) : null;
|
||||
const combinedSignal =
|
||||
signal && timeoutSignal
|
||||
? AbortSignal.any([signal, timeoutSignal])
|
||||
: signal || timeoutSignal;
|
||||
|
||||
const fetchOptions: Record<string, any> = {
|
||||
method: "POST",
|
||||
headers,
|
||||
body: JSON.stringify(transformedBody),
|
||||
};
|
||||
if (combinedSignal) fetchOptions.signal = combinedSignal;
|
||||
|
||||
const response = await fetch(url, fetchOptions);
|
||||
|
||||
if (this.shouldRetry(response.status, urlIndex)) {
|
||||
log?.debug?.("RETRY", `${response.status} on ${url}, trying fallback ${urlIndex + 1}`);
|
||||
lastStatus = response.status;
|
||||
continue;
|
||||
}
|
||||
|
||||
return { response, url, headers, transformedBody };
|
||||
} catch (error) {
|
||||
// Distinguish timeout errors from other abort errors
|
||||
if (error.name === "TimeoutError") {
|
||||
log?.warn?.("TIMEOUT", `Fetch timeout after ${FETCH_TIMEOUT_MS}ms on ${url}`);
|
||||
}
|
||||
lastError = error;
|
||||
if (urlIndex + 1 < fallbackCount) {
|
||||
log?.debug?.("RETRY", `Error on ${url}, trying fallback ${urlIndex + 1}`);
|
||||
continue;
|
||||
}
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
|
||||
throw lastError || new Error(`All ${fallbackCount} URLs failed with status ${lastStatus}`);
|
||||
}
|
||||
}
|
||||
|
||||
export default BaseExecutor;
|
||||
75
open-sse/executors/codex.ts
Normal file
75
open-sse/executors/codex.ts
Normal file
@@ -0,0 +1,75 @@
|
||||
import { BaseExecutor } from "./base.ts";
|
||||
import { CODEX_DEFAULT_INSTRUCTIONS } from "../config/codexInstructions.ts";
|
||||
import { PROVIDERS } from "../config/constants.ts";
|
||||
|
||||
/**
|
||||
* Codex Executor - handles OpenAI Codex API (Responses API format)
|
||||
* Automatically injects default instructions if missing
|
||||
*/
|
||||
export class CodexExecutor extends BaseExecutor {
|
||||
constructor() {
|
||||
super("codex", PROVIDERS.codex);
|
||||
}
|
||||
|
||||
/**
|
||||
* Codex Responses endpoint is SSE-first.
|
||||
* Always request event-stream from upstream, even when client requested stream=false.
|
||||
*/
|
||||
buildHeaders(credentials, stream = true) {
|
||||
return super.buildHeaders(credentials, true);
|
||||
}
|
||||
|
||||
/**
|
||||
* Transform request before sending - inject default instructions if missing
|
||||
*/
|
||||
transformRequest(model, body, stream, credentials) {
|
||||
// Codex /responses rejects stream=false; we aggregate SSE back to JSON when needed.
|
||||
body.stream = true;
|
||||
|
||||
// If no instructions provided, inject default Codex instructions
|
||||
if (!body.instructions || body.instructions.trim() === "") {
|
||||
body.instructions = CODEX_DEFAULT_INSTRUCTIONS;
|
||||
}
|
||||
|
||||
// Ensure store is false (Codex requirement)
|
||||
body.store = false;
|
||||
|
||||
// Extract thinking level from model name suffix
|
||||
// e.g., gpt-5.3-codex-high → high, gpt-5.3-codex → medium (default)
|
||||
const effortLevels = ["none", "low", "medium", "high", "xhigh"];
|
||||
let modelEffort = null;
|
||||
for (const level of effortLevels) {
|
||||
if (model.endsWith(`-${level}`)) {
|
||||
modelEffort = level;
|
||||
// Strip suffix from model name for actual API call
|
||||
body.model = body.model.replace(`-${level}`, "");
|
||||
break;
|
||||
}
|
||||
}
|
||||
|
||||
// Priority: explicit reasoning.effort > reasoning_effort param > model suffix > default (medium)
|
||||
if (!body.reasoning) {
|
||||
const effort = body.reasoning_effort || modelEffort || "medium";
|
||||
body.reasoning = { effort };
|
||||
}
|
||||
delete body.reasoning_effort;
|
||||
|
||||
// Remove unsupported parameters for Codex API
|
||||
delete body.temperature;
|
||||
delete body.top_p;
|
||||
delete body.frequency_penalty;
|
||||
delete body.presence_penalty;
|
||||
delete body.logprobs;
|
||||
delete body.top_logprobs;
|
||||
delete body.n;
|
||||
delete body.seed;
|
||||
delete body.max_tokens;
|
||||
delete body.user; // Cursor sends this but Codex doesn't support it
|
||||
delete body.prompt_cache_retention; // Cursor sends this but Codex doesn't support it
|
||||
delete body.metadata; // Cursor sends this but Codex doesn't support it
|
||||
delete body.stream_options; // Cursor sends this but Codex doesn't support it
|
||||
delete body.safety_identifier; // Droid CLI sends this but Codex doesn't support it
|
||||
|
||||
return body;
|
||||
}
|
||||
}
|
||||
739
open-sse/executors/cursor.ts
Normal file
739
open-sse/executors/cursor.ts
Normal file
@@ -0,0 +1,739 @@
|
||||
declare var EdgeRuntime: any;
|
||||
/**
|
||||
* CursorExecutor — Handles communication with the Cursor IDE API.
|
||||
*
|
||||
* This executor is the most complex due to Cursor's non-standard protocol:
|
||||
*
|
||||
* SECTION 1: Authentication (generateChecksum)
|
||||
* - SHA-256 based checksum using machine ID and timestamp
|
||||
* - WorkOS token refresh for session management
|
||||
*
|
||||
* SECTION 2: Request Encoding (transformRequest, buildHeaders)
|
||||
* - ConnectRPC Protobuf binary encoding via cursorProtobuf.js
|
||||
* - Chat body construction with model routing
|
||||
*
|
||||
* SECTION 3: Response Parsing (executeStream, parseEvent*)
|
||||
* - Binary EventStream → SSE text conversion
|
||||
* - Gzip decompression of response frames
|
||||
* - HTTP/2 support with h2 fallback to fetch
|
||||
*
|
||||
* @see cursorProtobuf.js for Protobuf encoding/decoding utilities
|
||||
*/
|
||||
|
||||
import { BaseExecutor } from "./base.ts";
|
||||
import { PROVIDERS, HTTP_STATUS } from "../config/constants.ts";
|
||||
import {
|
||||
generateCursorBody,
|
||||
parseConnectRPCFrame,
|
||||
extractTextFromResponse,
|
||||
} from "../utils/cursorProtobuf.ts";
|
||||
import { estimateUsage } from "../utils/usageTracking.ts";
|
||||
import { FORMATS } from "../translator/formats.ts";
|
||||
import { buildCursorRequest } from "../translator/request/openai-to-cursor.ts";
|
||||
import crypto from "crypto";
|
||||
import { v5 as uuidv5 } from "uuid";
|
||||
import zlib from "zlib";
|
||||
|
||||
// Detect cloud environment
|
||||
const isCloudEnv = () => {
|
||||
if (typeof caches !== "undefined" && typeof caches === "object") return true;
|
||||
if (typeof EdgeRuntime !== "undefined") return true;
|
||||
return false;
|
||||
};
|
||||
|
||||
// Lazy import http2 (only in Node.js environment)
|
||||
let http2 = null;
|
||||
if (!isCloudEnv()) {
|
||||
try {
|
||||
http2 = await import("http2");
|
||||
} catch {
|
||||
// http2 not available
|
||||
}
|
||||
}
|
||||
|
||||
// --- SECTION 1: Authentication Constants ---
|
||||
const COMPRESS_FLAG = {
|
||||
NONE: 0x00,
|
||||
GZIP: 0x01,
|
||||
GZIP_ALT: 0x02,
|
||||
GZIP_BOTH: 0x03,
|
||||
};
|
||||
|
||||
function decompressPayload(payload, flags) {
|
||||
// Check if payload is JSON error (starts with {"error")
|
||||
if (payload.length > 10 && payload[0] === 0x7b && payload[1] === 0x22) {
|
||||
try {
|
||||
const text = payload.toString("utf-8");
|
||||
if (text.startsWith('{"error"')) {
|
||||
console.log(`[DECOMPRESS] Detected JSON error, skipping decompression`);
|
||||
return payload;
|
||||
}
|
||||
} catch {}
|
||||
}
|
||||
|
||||
if (
|
||||
flags === COMPRESS_FLAG.GZIP ||
|
||||
flags === COMPRESS_FLAG.GZIP_ALT ||
|
||||
flags === COMPRESS_FLAG.GZIP_BOTH
|
||||
) {
|
||||
try {
|
||||
return zlib.gunzipSync(payload);
|
||||
} catch (err) {
|
||||
console.log(
|
||||
`[DECOMPRESS ERROR] flags=${flags}, payloadSize=${payload.length}, error=${err.message}`
|
||||
);
|
||||
console.log(`[DECOMPRESS ERROR] First 50 bytes (hex):`, payload.slice(0, 50).toString("hex"));
|
||||
console.log(
|
||||
`[DECOMPRESS ERROR] First 50 bytes (utf8):`,
|
||||
payload
|
||||
.slice(0, 50)
|
||||
.toString("utf8")
|
||||
.replace(/[^\x20-\x7E]/g, ".")
|
||||
);
|
||||
// Try to use payload as-is if decompression fails
|
||||
return payload;
|
||||
}
|
||||
}
|
||||
return payload;
|
||||
}
|
||||
|
||||
function createErrorResponse(jsonError) {
|
||||
const errorMsg =
|
||||
jsonError?.error?.details?.[0]?.debug?.details?.title ||
|
||||
jsonError?.error?.details?.[0]?.debug?.details?.detail ||
|
||||
jsonError?.error?.message ||
|
||||
"API Error";
|
||||
|
||||
const isRateLimit = jsonError?.error?.code === "resource_exhausted";
|
||||
|
||||
return new Response(
|
||||
JSON.stringify({
|
||||
error: {
|
||||
message: errorMsg,
|
||||
type: isRateLimit ? "rate_limit_error" : "api_error",
|
||||
code: jsonError?.error?.details?.[0]?.debug?.error || "unknown",
|
||||
},
|
||||
}),
|
||||
{
|
||||
status: isRateLimit ? HTTP_STATUS.RATE_LIMITED : HTTP_STATUS.BAD_REQUEST,
|
||||
headers: { "Content-Type": "application/json" },
|
||||
}
|
||||
);
|
||||
}
|
||||
|
||||
export class CursorExecutor extends BaseExecutor {
|
||||
constructor() {
|
||||
super("cursor", PROVIDERS.cursor);
|
||||
}
|
||||
|
||||
buildUrl() {
|
||||
return `${this.config.baseUrl}${this.config.chatPath}`;
|
||||
}
|
||||
|
||||
// Jyh cipher checksum for Cursor API authentication
|
||||
generateChecksum(machineId) {
|
||||
const timestamp = Math.floor(Date.now() / 1000000);
|
||||
const byteArray = new Uint8Array([
|
||||
(timestamp >> 40) & 0xff,
|
||||
(timestamp >> 32) & 0xff,
|
||||
(timestamp >> 24) & 0xff,
|
||||
(timestamp >> 16) & 0xff,
|
||||
(timestamp >> 8) & 0xff,
|
||||
timestamp & 0xff,
|
||||
]);
|
||||
|
||||
let t = 165;
|
||||
for (let i = 0; i < byteArray.length; i++) {
|
||||
byteArray[i] = ((byteArray[i] ^ t) + (i % 256)) & 0xff;
|
||||
t = byteArray[i];
|
||||
}
|
||||
|
||||
const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
|
||||
let encoded = "";
|
||||
|
||||
for (let i = 0; i < byteArray.length; i += 3) {
|
||||
const a = byteArray[i];
|
||||
const b = i + 1 < byteArray.length ? byteArray[i + 1] : 0;
|
||||
const c = i + 2 < byteArray.length ? byteArray[i + 2] : 0;
|
||||
|
||||
encoded += alphabet[a >> 2];
|
||||
encoded += alphabet[((a & 3) << 4) | (b >> 4)];
|
||||
|
||||
if (i + 1 < byteArray.length) {
|
||||
encoded += alphabet[((b & 15) << 2) | (c >> 6)];
|
||||
}
|
||||
if (i + 2 < byteArray.length) {
|
||||
encoded += alphabet[c & 63];
|
||||
}
|
||||
}
|
||||
|
||||
return `${encoded}${machineId}`;
|
||||
}
|
||||
|
||||
buildHeaders(credentials) {
|
||||
const accessToken = credentials.accessToken;
|
||||
const machineId = credentials.providerSpecificData?.machineId;
|
||||
const ghostMode = credentials.providerSpecificData?.ghostMode !== false;
|
||||
|
||||
if (!machineId) {
|
||||
throw new Error("Machine ID is required for Cursor API");
|
||||
}
|
||||
|
||||
const cleanToken = accessToken.includes("::") ? accessToken.split("::")[1] : accessToken;
|
||||
|
||||
return {
|
||||
authorization: `Bearer ${cleanToken}`,
|
||||
"connect-accept-encoding": "gzip",
|
||||
"connect-protocol-version": "1",
|
||||
"content-type": "application/connect+proto",
|
||||
"user-agent": "connect-es/1.6.1",
|
||||
"x-amzn-trace-id": `Root=${crypto.randomUUID()}`,
|
||||
"x-client-key": crypto.createHash("sha256").update(cleanToken).digest("hex"),
|
||||
"x-cursor-checksum": this.generateChecksum(machineId),
|
||||
"x-cursor-client-version": "2.3.41",
|
||||
"x-cursor-client-type": "ide",
|
||||
"x-cursor-client-os":
|
||||
process.platform === "win32"
|
||||
? "windows"
|
||||
: process.platform === "darwin"
|
||||
? "macos"
|
||||
: "linux",
|
||||
"x-cursor-client-arch": process.arch === "arm64" ? "aarch64" : "x64",
|
||||
"x-cursor-client-device-type": "desktop",
|
||||
"x-cursor-config-version": crypto.randomUUID(),
|
||||
"x-cursor-timezone": Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC",
|
||||
"x-ghost-mode": ghostMode ? "true" : "false",
|
||||
"x-request-id": crypto.randomUUID(),
|
||||
"x-session-id": uuidv5(cleanToken, uuidv5.DNS),
|
||||
};
|
||||
}
|
||||
|
||||
transformRequest(model, body, stream, credentials) {
|
||||
// Call translator to convert OpenAI format to Cursor format
|
||||
const translatedBody = buildCursorRequest(model, body, stream, credentials);
|
||||
const messages = translatedBody.messages || [];
|
||||
const tools = translatedBody.tools || body.tools || [];
|
||||
const reasoningEffort = body.reasoning_effort || null;
|
||||
return generateCursorBody(messages, model, tools, reasoningEffort);
|
||||
}
|
||||
|
||||
async makeFetchRequest(url, headers, body, signal) {
|
||||
const response = await fetch(url, {
|
||||
method: "POST",
|
||||
headers,
|
||||
body,
|
||||
signal,
|
||||
});
|
||||
|
||||
return {
|
||||
status: response.status,
|
||||
headers: Object.fromEntries((response.headers as any).entries()),
|
||||
body: Buffer.from(await response.arrayBuffer()),
|
||||
};
|
||||
}
|
||||
|
||||
makeHttp2Request(url, headers, body, signal) {
|
||||
if (!http2) {
|
||||
throw new Error("http2 module not available");
|
||||
}
|
||||
|
||||
return new Promise((resolve, reject) => {
|
||||
const urlObj = new URL(url);
|
||||
const client = http2.connect(`https://${urlObj.host}`);
|
||||
const chunks = [];
|
||||
let responseHeaders = {};
|
||||
|
||||
client.on("error", reject);
|
||||
|
||||
const req = client.request({
|
||||
":method": "POST",
|
||||
":path": urlObj.pathname,
|
||||
":authority": urlObj.host,
|
||||
":scheme": "https",
|
||||
...headers,
|
||||
});
|
||||
|
||||
req.on("response", (hdrs) => {
|
||||
responseHeaders = hdrs;
|
||||
});
|
||||
req.on("data", (chunk) => {
|
||||
chunks.push(chunk);
|
||||
});
|
||||
req.on("end", () => {
|
||||
client.close();
|
||||
resolve({
|
||||
status: responseHeaders[":status"],
|
||||
headers: responseHeaders,
|
||||
body: Buffer.concat(chunks),
|
||||
});
|
||||
});
|
||||
req.on("error", (err) => {
|
||||
client.close();
|
||||
reject(err);
|
||||
});
|
||||
|
||||
if (signal) {
|
||||
signal.addEventListener("abort", () => {
|
||||
req.close();
|
||||
client.close();
|
||||
reject(new Error("Request aborted"));
|
||||
});
|
||||
}
|
||||
|
||||
req.write(body);
|
||||
req.end();
|
||||
});
|
||||
}
|
||||
|
||||
async execute({ model, body, stream, credentials, signal, log }) {
|
||||
const url = this.buildUrl();
|
||||
const headers = this.buildHeaders(credentials);
|
||||
const transformedBody = this.transformRequest(model, body, stream, credentials);
|
||||
|
||||
try {
|
||||
const response: any = http2
|
||||
? await this.makeHttp2Request(url, headers, transformedBody, signal)
|
||||
: await this.makeFetchRequest(url, headers, transformedBody, signal);
|
||||
|
||||
if (response.status !== 200) {
|
||||
const errorText = response.body?.toString() || "Unknown error";
|
||||
const errorResponse = new Response(
|
||||
JSON.stringify({
|
||||
error: {
|
||||
message: `[${response.status}]: ${errorText}`,
|
||||
type: "invalid_request_error",
|
||||
code: "",
|
||||
},
|
||||
}),
|
||||
{
|
||||
status: response.status,
|
||||
headers: { "Content-Type": "application/json" },
|
||||
}
|
||||
);
|
||||
return { response: errorResponse, url, headers, transformedBody: body };
|
||||
}
|
||||
|
||||
const transformedResponse =
|
||||
stream !== false
|
||||
? this.transformProtobufToSSE(response.body, model, body)
|
||||
: this.transformProtobufToJSON(response.body, model, body);
|
||||
|
||||
return { response: transformedResponse, url, headers, transformedBody: body };
|
||||
} catch (error) {
|
||||
const errorResponse = new Response(
|
||||
JSON.stringify({
|
||||
error: {
|
||||
message: error.message,
|
||||
type: "connection_error",
|
||||
code: "",
|
||||
},
|
||||
}),
|
||||
{
|
||||
status: HTTP_STATUS.SERVER_ERROR,
|
||||
headers: { "Content-Type": "application/json" },
|
||||
}
|
||||
);
|
||||
return { response: errorResponse, url, headers, transformedBody: body };
|
||||
}
|
||||
}
|
||||
|
||||
transformProtobufToJSON(buffer, model, body) {
|
||||
const responseId = `chatcmpl-cursor-${Date.now()}`;
|
||||
const created = Math.floor(Date.now() / 1000);
|
||||
|
||||
let offset = 0;
|
||||
let totalContent = "";
|
||||
const toolCalls = [];
|
||||
const toolCallsMap = new Map(); // Track streaming tool calls by ID
|
||||
let frameCount = 0;
|
||||
|
||||
console.log(`[CURSOR BUFFER] Total length: ${buffer.length} bytes`);
|
||||
|
||||
while (offset < buffer.length) {
|
||||
if (offset + 5 > buffer.length) {
|
||||
console.log(
|
||||
`[CURSOR BUFFER] Reached end, offset=${offset}, remaining=${buffer.length - offset}`
|
||||
);
|
||||
break;
|
||||
}
|
||||
|
||||
const flags = buffer[offset];
|
||||
const length = buffer.readUInt32BE(offset + 1);
|
||||
|
||||
console.log(
|
||||
`[CURSOR BUFFER] Frame ${frameCount + 1}: flags=0x${flags.toString(16).padStart(2, "0")}, length=${length}`
|
||||
);
|
||||
|
||||
if (offset + 5 + length > buffer.length) {
|
||||
console.log(
|
||||
`[CURSOR BUFFER] Incomplete frame, offset=${offset}, length=${length}, buffer.length=${buffer.length}`
|
||||
);
|
||||
break;
|
||||
}
|
||||
|
||||
let payload = buffer.slice(offset + 5, offset + 5 + length);
|
||||
offset += 5 + length;
|
||||
frameCount++;
|
||||
|
||||
payload = decompressPayload(payload, flags);
|
||||
if (!payload) {
|
||||
console.log(`[CURSOR BUFFER] Frame ${frameCount}: decompression failed, skipping`);
|
||||
continue;
|
||||
}
|
||||
|
||||
try {
|
||||
const text = payload.toString("utf-8");
|
||||
if (text.startsWith("{") && text.includes('"error"')) {
|
||||
return createErrorResponse(JSON.parse(text));
|
||||
}
|
||||
} catch {}
|
||||
|
||||
const result = extractTextFromResponse(new Uint8Array(payload));
|
||||
console.log(`[CURSOR DECODED] Frame ${frameCount}:`, result);
|
||||
|
||||
if (result.error) {
|
||||
return new Response(
|
||||
JSON.stringify({
|
||||
error: {
|
||||
message: result.error,
|
||||
type: "rate_limit_error",
|
||||
code: "rate_limited",
|
||||
},
|
||||
}),
|
||||
{
|
||||
status: HTTP_STATUS.RATE_LIMITED,
|
||||
headers: { "Content-Type": "application/json" },
|
||||
}
|
||||
);
|
||||
}
|
||||
|
||||
if (result.toolCall) {
|
||||
const tc = result.toolCall;
|
||||
|
||||
if (toolCallsMap.has(tc.id)) {
|
||||
// Accumulate arguments for existing tool call
|
||||
const existing = toolCallsMap.get(tc.id);
|
||||
existing.function.arguments += tc.function.arguments;
|
||||
existing.isLast = tc.isLast;
|
||||
} else {
|
||||
// New tool call
|
||||
toolCallsMap.set(tc.id, { ...tc });
|
||||
}
|
||||
|
||||
// Push to final array when isLast is true
|
||||
if (tc.isLast) {
|
||||
const finalToolCall = toolCallsMap.get(tc.id);
|
||||
toolCalls.push({
|
||||
id: finalToolCall.id,
|
||||
type: finalToolCall.type,
|
||||
function: {
|
||||
name: finalToolCall.function.name,
|
||||
arguments: finalToolCall.function.arguments,
|
||||
},
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
if (result.text) totalContent += result.text;
|
||||
}
|
||||
|
||||
console.log(
|
||||
`[CURSOR BUFFER] Parsed ${frameCount} frames, toolCallsMap size: ${toolCallsMap.size}, finalized toolCalls: ${toolCalls.length}`
|
||||
);
|
||||
|
||||
// Finalize all remaining tool calls in map (in case stream ended without isLast=true)
|
||||
for (const [id, tc] of toolCallsMap.entries()) {
|
||||
// Check if already in final array
|
||||
if (!toolCalls.find((t) => t.id === id)) {
|
||||
console.log(`[CURSOR BUFFER] Finalizing incomplete tool call: ${id}, isLast=${tc.isLast}`);
|
||||
toolCalls.push({
|
||||
id: tc.id,
|
||||
type: tc.type,
|
||||
function: {
|
||||
name: tc.function.name,
|
||||
arguments: tc.function.arguments,
|
||||
},
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
console.log(`[CURSOR BUFFER] Final toolCalls count: ${toolCalls.length}`);
|
||||
|
||||
const message: Record<string, any> = { role: "assistant",
|
||||
content: totalContent || null,
|
||||
};
|
||||
|
||||
if (toolCalls.length > 0) {
|
||||
message.tool_calls = toolCalls;
|
||||
}
|
||||
|
||||
const usage = estimateUsage(body, totalContent.length, FORMATS.OPENAI);
|
||||
|
||||
const completion = {
|
||||
id: responseId,
|
||||
object: "chat.completion",
|
||||
created,
|
||||
model,
|
||||
choices: [
|
||||
{
|
||||
index: 0,
|
||||
message,
|
||||
finish_reason: toolCalls.length > 0 ? "tool_calls" : "stop",
|
||||
},
|
||||
],
|
||||
usage,
|
||||
};
|
||||
|
||||
return new Response(JSON.stringify(completion), {
|
||||
status: 200,
|
||||
headers: { "Content-Type": "application/json" },
|
||||
});
|
||||
}
|
||||
|
||||
transformProtobufToSSE(buffer, model, body) {
|
||||
const responseId = `chatcmpl-cursor-${Date.now()}`;
|
||||
const created = Math.floor(Date.now() / 1000);
|
||||
|
||||
const chunks = [];
|
||||
let offset = 0;
|
||||
let totalContent = "";
|
||||
const toolCalls = [];
|
||||
const toolCallsMap = new Map(); // Track streaming tool calls by ID
|
||||
let frameCount = 0;
|
||||
|
||||
console.log(`[CURSOR BUFFER SSE] Total length: ${buffer.length} bytes`);
|
||||
|
||||
while (offset < buffer.length) {
|
||||
if (offset + 5 > buffer.length) {
|
||||
console.log(
|
||||
`[CURSOR BUFFER SSE] Reached end, offset=${offset}, remaining=${buffer.length - offset}`
|
||||
);
|
||||
break;
|
||||
}
|
||||
|
||||
const flags = buffer[offset];
|
||||
const length = buffer.readUInt32BE(offset + 1);
|
||||
|
||||
console.log(
|
||||
`[CURSOR BUFFER SSE] Frame ${frameCount + 1}: flags=0x${flags.toString(16).padStart(2, "0")}, length=${length}`
|
||||
);
|
||||
|
||||
if (offset + 5 + length > buffer.length) {
|
||||
console.log(
|
||||
`[CURSOR BUFFER SSE] Incomplete frame, offset=${offset}, length=${length}, buffer.length=${buffer.length}`
|
||||
);
|
||||
break;
|
||||
}
|
||||
|
||||
let payload = buffer.slice(offset + 5, offset + 5 + length);
|
||||
offset += 5 + length;
|
||||
frameCount++;
|
||||
|
||||
payload = decompressPayload(payload, flags);
|
||||
if (!payload) {
|
||||
console.log(`[CURSOR BUFFER SSE] Frame ${frameCount}: decompression failed, skipping`);
|
||||
continue;
|
||||
}
|
||||
|
||||
try {
|
||||
const text = payload.toString("utf-8");
|
||||
if (text.startsWith("{") && text.includes('"error"')) {
|
||||
return createErrorResponse(JSON.parse(text));
|
||||
}
|
||||
} catch {}
|
||||
|
||||
const result = extractTextFromResponse(new Uint8Array(payload));
|
||||
console.log(`[CURSOR DECODED SSE] Frame ${frameCount}:`, result);
|
||||
|
||||
if (result.error) {
|
||||
return new Response(
|
||||
JSON.stringify({
|
||||
error: {
|
||||
message: result.error,
|
||||
type: "rate_limit_error",
|
||||
code: "rate_limited",
|
||||
},
|
||||
}),
|
||||
{
|
||||
status: HTTP_STATUS.RATE_LIMITED,
|
||||
headers: { "Content-Type": "application/json" },
|
||||
}
|
||||
);
|
||||
}
|
||||
|
||||
if (result.toolCall) {
|
||||
const tc = result.toolCall;
|
||||
|
||||
if (chunks.length === 0) {
|
||||
chunks.push(
|
||||
`data: ${JSON.stringify({
|
||||
id: responseId,
|
||||
object: "chat.completion.chunk",
|
||||
created,
|
||||
model,
|
||||
choices: [
|
||||
{
|
||||
index: 0,
|
||||
delta: { role: "assistant", content: "" },
|
||||
finish_reason: null,
|
||||
},
|
||||
],
|
||||
})}\n\n`
|
||||
);
|
||||
}
|
||||
|
||||
if (toolCallsMap.has(tc.id)) {
|
||||
// Accumulate arguments for existing tool call
|
||||
const existing = toolCallsMap.get(tc.id);
|
||||
const oldArgsLen = existing.function.arguments.length;
|
||||
existing.function.arguments += tc.function.arguments;
|
||||
existing.isLast = tc.isLast;
|
||||
|
||||
// Stream the delta arguments
|
||||
if (tc.function.arguments) {
|
||||
chunks.push(
|
||||
`data: ${JSON.stringify({
|
||||
id: responseId,
|
||||
object: "chat.completion.chunk",
|
||||
created,
|
||||
model,
|
||||
choices: [
|
||||
{
|
||||
index: 0,
|
||||
delta: {
|
||||
tool_calls: [
|
||||
{
|
||||
index: existing.index,
|
||||
id: tc.id,
|
||||
type: "function",
|
||||
function: {
|
||||
name: tc.function.name,
|
||||
arguments: tc.function.arguments,
|
||||
},
|
||||
},
|
||||
],
|
||||
},
|
||||
finish_reason: null,
|
||||
},
|
||||
],
|
||||
})}\n\n`
|
||||
);
|
||||
}
|
||||
} else {
|
||||
// New tool call - assign index and add to map
|
||||
const toolCallIndex = toolCalls.length;
|
||||
toolCalls.push({ ...tc, index: toolCallIndex });
|
||||
toolCallsMap.set(tc.id, { ...tc, index: toolCallIndex });
|
||||
|
||||
// Stream initial tool call with name
|
||||
chunks.push(
|
||||
`data: ${JSON.stringify({
|
||||
id: responseId,
|
||||
object: "chat.completion.chunk",
|
||||
created,
|
||||
model,
|
||||
choices: [
|
||||
{
|
||||
index: 0,
|
||||
delta: {
|
||||
tool_calls: [
|
||||
{
|
||||
index: toolCallIndex,
|
||||
id: tc.id,
|
||||
type: "function",
|
||||
function: {
|
||||
name: tc.function.name,
|
||||
arguments: tc.function.arguments,
|
||||
},
|
||||
},
|
||||
],
|
||||
},
|
||||
finish_reason: null,
|
||||
},
|
||||
],
|
||||
})}\n\n`
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
if (result.text) {
|
||||
totalContent += result.text;
|
||||
chunks.push(
|
||||
`data: ${JSON.stringify({
|
||||
id: responseId,
|
||||
object: "chat.completion.chunk",
|
||||
created,
|
||||
model,
|
||||
choices: [
|
||||
{
|
||||
index: 0,
|
||||
delta:
|
||||
chunks.length === 0 && toolCalls.length === 0
|
||||
? { role: "assistant", content: result.text }
|
||||
: { content: result.text },
|
||||
finish_reason: null,
|
||||
},
|
||||
],
|
||||
})}\n\n`
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
console.log(
|
||||
`[CURSOR BUFFER SSE] Parsed ${frameCount} frames, toolCallsMap size: ${toolCallsMap.size}, toolCalls array: ${toolCalls.length}`
|
||||
);
|
||||
|
||||
if (chunks.length === 0 && toolCalls.length === 0) {
|
||||
chunks.push(
|
||||
`data: ${JSON.stringify({
|
||||
id: responseId,
|
||||
object: "chat.completion.chunk",
|
||||
created,
|
||||
model,
|
||||
choices: [
|
||||
{
|
||||
index: 0,
|
||||
delta: { role: "assistant", content: "" },
|
||||
finish_reason: null,
|
||||
},
|
||||
],
|
||||
})}\n\n`
|
||||
);
|
||||
}
|
||||
|
||||
const usage = estimateUsage(body, totalContent.length, FORMATS.OPENAI);
|
||||
|
||||
chunks.push(
|
||||
`data: ${JSON.stringify({
|
||||
id: responseId,
|
||||
object: "chat.completion.chunk",
|
||||
created,
|
||||
model,
|
||||
choices: [
|
||||
{
|
||||
index: 0,
|
||||
delta: {},
|
||||
finish_reason: toolCalls.length > 0 ? "tool_calls" : "stop",
|
||||
},
|
||||
],
|
||||
usage,
|
||||
})}\n\n`
|
||||
);
|
||||
chunks.push("data: [DONE]\n\n");
|
||||
|
||||
return new Response(chunks.join(""), {
|
||||
status: 200,
|
||||
headers: {
|
||||
"Content-Type": "text/event-stream",
|
||||
"Cache-Control": "no-cache",
|
||||
Connection: "keep-alive",
|
||||
},
|
||||
});
|
||||
}
|
||||
|
||||
async refreshCredentials() {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
export default CursorExecutor;
|
||||
107
open-sse/executors/default.ts
Normal file
107
open-sse/executors/default.ts
Normal file
@@ -0,0 +1,107 @@
|
||||
import { BaseExecutor } from "./base.ts";
|
||||
import { PROVIDERS, OAUTH_ENDPOINTS } from "../config/constants.ts";
|
||||
import { getAccessToken } from "../services/tokenRefresh.ts";
|
||||
|
||||
export class DefaultExecutor extends BaseExecutor {
|
||||
constructor(provider) {
|
||||
super(provider, PROVIDERS[provider] || PROVIDERS.openai);
|
||||
}
|
||||
|
||||
buildUrl(model, stream, urlIndex = 0, credentials = null) {
|
||||
if (this.provider?.startsWith?.("openai-compatible-")) {
|
||||
const baseUrl = credentials?.providerSpecificData?.baseUrl || "https://api.openai.com/v1";
|
||||
const normalized = baseUrl.replace(/\/$/, "");
|
||||
const path = this.provider.includes("responses") ? "/responses" : "/chat/completions";
|
||||
return `${normalized}${path}`;
|
||||
}
|
||||
if (this.provider?.startsWith?.("anthropic-compatible-")) {
|
||||
const baseUrl = credentials?.providerSpecificData?.baseUrl || "https://api.anthropic.com/v1";
|
||||
const normalized = baseUrl.replace(/\/$/, "");
|
||||
return `${normalized}/messages`;
|
||||
}
|
||||
switch (this.provider) {
|
||||
case "claude":
|
||||
case "glm":
|
||||
case "kimi-coding":
|
||||
case "minimax":
|
||||
case "minimax-cn":
|
||||
return `${this.config.baseUrl}?beta=true`;
|
||||
case "gemini":
|
||||
return `${this.config.baseUrl}/${model}:${stream ? "streamGenerateContent?alt=sse" : "generateContent"}`;
|
||||
default:
|
||||
return this.config.baseUrl;
|
||||
}
|
||||
}
|
||||
|
||||
buildHeaders(credentials, stream = true) {
|
||||
const headers = { "Content-Type": "application/json", ...this.config.headers };
|
||||
|
||||
switch (this.provider) {
|
||||
case "gemini":
|
||||
credentials.apiKey
|
||||
? (headers["x-goog-api-key"] = credentials.apiKey)
|
||||
: (headers["Authorization"] = `Bearer ${credentials.accessToken}`);
|
||||
break;
|
||||
case "claude":
|
||||
credentials.apiKey
|
||||
? (headers["x-api-key"] = credentials.apiKey)
|
||||
: (headers["Authorization"] = `Bearer ${credentials.accessToken}`);
|
||||
break;
|
||||
case "glm":
|
||||
case "kimi-coding":
|
||||
case "minimax":
|
||||
case "minimax-cn":
|
||||
headers["x-api-key"] = credentials.apiKey || credentials.accessToken;
|
||||
break;
|
||||
default:
|
||||
if (this.provider?.startsWith?.("anthropic-compatible-")) {
|
||||
if (credentials.apiKey) {
|
||||
headers["x-api-key"] = credentials.apiKey;
|
||||
} else if (credentials.accessToken) {
|
||||
headers["Authorization"] = `Bearer ${credentials.accessToken}`;
|
||||
}
|
||||
if (!headers["anthropic-version"]) {
|
||||
headers["anthropic-version"] = "2023-06-01";
|
||||
}
|
||||
} else {
|
||||
headers["Authorization"] = `Bearer ${credentials.apiKey || credentials.accessToken}`;
|
||||
}
|
||||
}
|
||||
|
||||
if (stream) headers["Accept"] = "text/event-stream";
|
||||
return headers;
|
||||
}
|
||||
|
||||
/**
|
||||
* For compatible providers, ensure the model name sent upstream
|
||||
* is the clean model name without any internal routing prefix.
|
||||
* e.g. "openapi-chat-anti/claude-opus-4-6-thinking" → "claude-opus-4-6-thinking"
|
||||
*/
|
||||
transformRequest(model, body, stream, credentials) {
|
||||
if (
|
||||
this.provider?.startsWith?.("openai-compatible-") ||
|
||||
this.provider?.startsWith?.("anthropic-compatible-")
|
||||
) {
|
||||
const cleanModel = model.includes("/") ? model.split("/").pop() : model;
|
||||
return { ...body, model: cleanModel };
|
||||
}
|
||||
return body;
|
||||
}
|
||||
|
||||
/**
|
||||
* Refresh credentials via the centralized tokenRefresh service.
|
||||
* Delegates to getAccessToken() which handles all providers with
|
||||
* race-condition protection (deduplication via refreshPromiseCache).
|
||||
*/
|
||||
async refreshCredentials(credentials, log) {
|
||||
if (!credentials.refreshToken) return null;
|
||||
try {
|
||||
return await getAccessToken(this.provider, credentials, log);
|
||||
} catch (error) {
|
||||
log?.error?.("TOKEN", `${this.provider} refresh error: ${error.message}`);
|
||||
return null;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
export default DefaultExecutor;
|
||||
65
open-sse/executors/gemini-cli.ts
Normal file
65
open-sse/executors/gemini-cli.ts
Normal file
@@ -0,0 +1,65 @@
|
||||
import { BaseExecutor } from "./base.ts";
|
||||
import { PROVIDERS, OAUTH_ENDPOINTS } from "../config/constants.ts";
|
||||
|
||||
export class GeminiCLIExecutor extends BaseExecutor {
|
||||
constructor() {
|
||||
super("gemini-cli", PROVIDERS["gemini-cli"]);
|
||||
}
|
||||
|
||||
buildUrl(model, stream, urlIndex = 0) {
|
||||
const action = stream ? "streamGenerateContent?alt=sse" : "generateContent";
|
||||
return `${this.config.baseUrl}:${action}`;
|
||||
}
|
||||
|
||||
buildHeaders(credentials, stream = true) {
|
||||
return {
|
||||
"Content-Type": "application/json",
|
||||
Authorization: `Bearer ${credentials.accessToken}`,
|
||||
...(stream && { Accept: "text/event-stream" }),
|
||||
};
|
||||
}
|
||||
|
||||
transformRequest(model, body, stream, credentials) {
|
||||
if (!body.project && credentials?.projectId) {
|
||||
body.project = credentials.projectId;
|
||||
}
|
||||
return body;
|
||||
}
|
||||
|
||||
async refreshCredentials(credentials, log) {
|
||||
if (!credentials.refreshToken) return null;
|
||||
|
||||
try {
|
||||
const response = await fetch(OAUTH_ENDPOINTS.google.token, {
|
||||
method: "POST",
|
||||
headers: {
|
||||
"Content-Type": "application/x-www-form-urlencoded",
|
||||
Accept: "application/json",
|
||||
},
|
||||
body: new URLSearchParams({
|
||||
grant_type: "refresh_token",
|
||||
refresh_token: credentials.refreshToken,
|
||||
client_id: this.config.clientId,
|
||||
client_secret: this.config.clientSecret,
|
||||
}),
|
||||
});
|
||||
|
||||
if (!response.ok) return null;
|
||||
|
||||
const tokens = await response.json();
|
||||
log?.info?.("TOKEN", "Gemini CLI refreshed");
|
||||
|
||||
return {
|
||||
accessToken: tokens.access_token,
|
||||
refreshToken: tokens.refresh_token || credentials.refreshToken,
|
||||
expiresIn: tokens.expires_in,
|
||||
projectId: credentials.projectId,
|
||||
};
|
||||
} catch (error) {
|
||||
log?.error?.("TOKEN", `Gemini CLI refresh error: ${error.message}`);
|
||||
return null;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
export default GeminiCLIExecutor;
|
||||
139
open-sse/executors/github.ts
Normal file
139
open-sse/executors/github.ts
Normal file
@@ -0,0 +1,139 @@
|
||||
import { BaseExecutor } from "./base.ts";
|
||||
import { PROVIDERS, OAUTH_ENDPOINTS } from "../config/constants.ts";
|
||||
import { getModelTargetFormat } from "../config/providerModels.ts";
|
||||
|
||||
export class GithubExecutor extends BaseExecutor {
|
||||
constructor() {
|
||||
super("github", PROVIDERS.github);
|
||||
}
|
||||
|
||||
buildUrl(model, stream, urlIndex = 0) {
|
||||
const targetFormat = getModelTargetFormat("gh", model);
|
||||
if (targetFormat === "openai-responses") {
|
||||
return (
|
||||
this.config.responsesBaseUrl ||
|
||||
this.config.baseUrl?.replace(/\/chat\/completions\/?$/, "/responses") ||
|
||||
"https://api.githubcopilot.com/responses"
|
||||
);
|
||||
}
|
||||
return this.config.baseUrl;
|
||||
}
|
||||
|
||||
buildHeaders(credentials, stream = true) {
|
||||
const token = credentials.copilotToken || credentials.accessToken;
|
||||
return {
|
||||
Authorization: `Bearer ${token}`,
|
||||
"Content-Type": "application/json",
|
||||
"copilot-integration-id": "vscode-chat",
|
||||
"editor-version": "vscode/1.107.1",
|
||||
"editor-plugin-version": "copilot-chat/0.26.7",
|
||||
"user-agent": "GitHubCopilotChat/0.26.7",
|
||||
"openai-intent": "conversation-panel",
|
||||
"x-github-api-version": "2025-04-01",
|
||||
"x-request-id":
|
||||
crypto.randomUUID?.() || `${Date.now()}-${Math.random().toString(36).slice(2)}`,
|
||||
"x-vscode-user-agent-library-version": "electron-fetch",
|
||||
"X-Initiator": "user",
|
||||
Accept: stream ? "text/event-stream" : "application/json",
|
||||
};
|
||||
}
|
||||
|
||||
async refreshCopilotToken(githubAccessToken, log) {
|
||||
try {
|
||||
const response = await fetch("https://api.github.com/copilot_internal/v2/token", {
|
||||
headers: {
|
||||
Authorization: `token ${githubAccessToken}`,
|
||||
"User-Agent": "GithubCopilot/1.0",
|
||||
"Editor-Version": "vscode/1.100.0",
|
||||
"Editor-Plugin-Version": "copilot/1.300.0",
|
||||
Accept: "application/json",
|
||||
},
|
||||
});
|
||||
if (!response.ok) return null;
|
||||
const data = await response.json();
|
||||
log?.info?.("TOKEN", "Copilot token refreshed");
|
||||
return { token: data.token, expiresAt: data.expires_at };
|
||||
} catch (error) {
|
||||
log?.error?.("TOKEN", `Copilot refresh error: ${error.message}`);
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
async refreshGitHubToken(refreshToken, log) {
|
||||
try {
|
||||
const response = await fetch(OAUTH_ENDPOINTS.github.token, {
|
||||
method: "POST",
|
||||
headers: {
|
||||
"Content-Type": "application/x-www-form-urlencoded",
|
||||
Accept: "application/json",
|
||||
},
|
||||
body: new URLSearchParams({
|
||||
grant_type: "refresh_token",
|
||||
refresh_token: refreshToken,
|
||||
client_id: this.config.clientId,
|
||||
client_secret: this.config.clientSecret,
|
||||
}),
|
||||
});
|
||||
if (!response.ok) return null;
|
||||
const tokens = await response.json();
|
||||
log?.info?.("TOKEN", "GitHub token refreshed");
|
||||
return {
|
||||
accessToken: tokens.access_token,
|
||||
refreshToken: tokens.refresh_token || refreshToken,
|
||||
expiresIn: tokens.expires_in,
|
||||
};
|
||||
} catch (error) {
|
||||
log?.error?.("TOKEN", `GitHub refresh error: ${error.message}`);
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
async refreshCredentials(credentials, log) {
|
||||
let copilotResult = await this.refreshCopilotToken(credentials.accessToken, log);
|
||||
|
||||
if (!copilotResult && credentials.refreshToken) {
|
||||
const githubTokens = await this.refreshGitHubToken(credentials.refreshToken, log);
|
||||
if (githubTokens?.accessToken) {
|
||||
copilotResult = await this.refreshCopilotToken(githubTokens.accessToken, log);
|
||||
if (copilotResult) {
|
||||
return {
|
||||
...githubTokens,
|
||||
copilotToken: copilotResult.token,
|
||||
copilotTokenExpiresAt: copilotResult.expiresAt,
|
||||
};
|
||||
}
|
||||
return githubTokens;
|
||||
}
|
||||
}
|
||||
|
||||
if (copilotResult) {
|
||||
return {
|
||||
accessToken: credentials.accessToken,
|
||||
refreshToken: credentials.refreshToken,
|
||||
copilotToken: copilotResult.token,
|
||||
copilotTokenExpiresAt: copilotResult.expiresAt,
|
||||
};
|
||||
}
|
||||
|
||||
return null;
|
||||
}
|
||||
|
||||
needsRefresh(credentials) {
|
||||
// Always refresh if no copilotToken
|
||||
if (!credentials.copilotToken) return true;
|
||||
|
||||
if (credentials.copilotTokenExpiresAt) {
|
||||
// Handle both Unix timestamp (seconds) and ISO string
|
||||
let expiresAtMs = credentials.copilotTokenExpiresAt;
|
||||
if (typeof expiresAtMs === "number" && expiresAtMs < 1e12) {
|
||||
expiresAtMs = expiresAtMs * 1000; // Convert seconds to ms
|
||||
} else if (typeof expiresAtMs === "string") {
|
||||
expiresAtMs = new Date(expiresAtMs).getTime();
|
||||
}
|
||||
if (expiresAtMs - Date.now() < 5 * 60 * 1000) return true;
|
||||
}
|
||||
return super.needsRefresh(credentials);
|
||||
}
|
||||
}
|
||||
|
||||
export default GithubExecutor;
|
||||
38
open-sse/executors/index.ts
Normal file
38
open-sse/executors/index.ts
Normal file
@@ -0,0 +1,38 @@
|
||||
import { AntigravityExecutor } from "./antigravity.ts";
|
||||
import { GeminiCLIExecutor } from "./gemini-cli.ts";
|
||||
import { GithubExecutor } from "./github.ts";
|
||||
import { KiroExecutor } from "./kiro.ts";
|
||||
import { CodexExecutor } from "./codex.ts";
|
||||
import { CursorExecutor } from "./cursor.ts";
|
||||
import { DefaultExecutor } from "./default.ts";
|
||||
|
||||
const executors = {
|
||||
antigravity: new AntigravityExecutor(),
|
||||
"gemini-cli": new GeminiCLIExecutor(),
|
||||
github: new GithubExecutor(),
|
||||
kiro: new KiroExecutor(),
|
||||
codex: new CodexExecutor(),
|
||||
cursor: new CursorExecutor(),
|
||||
cu: new CursorExecutor(), // Alias for cursor
|
||||
};
|
||||
|
||||
const defaultCache = new Map();
|
||||
|
||||
export function getExecutor(provider) {
|
||||
if (executors[provider]) return executors[provider];
|
||||
if (!defaultCache.has(provider)) defaultCache.set(provider, new DefaultExecutor(provider));
|
||||
return defaultCache.get(provider);
|
||||
}
|
||||
|
||||
export function hasSpecializedExecutor(provider) {
|
||||
return !!executors[provider];
|
||||
}
|
||||
|
||||
export { BaseExecutor } from "./base.ts";
|
||||
export { AntigravityExecutor } from "./antigravity.ts";
|
||||
export { GeminiCLIExecutor } from "./gemini-cli.ts";
|
||||
export { GithubExecutor } from "./github.ts";
|
||||
export { KiroExecutor } from "./kiro.ts";
|
||||
export { CodexExecutor } from "./codex.ts";
|
||||
export { CursorExecutor } from "./cursor.ts";
|
||||
export { DefaultExecutor } from "./default.ts";
|
||||
510
open-sse/executors/kiro.ts
Normal file
510
open-sse/executors/kiro.ts
Normal file
@@ -0,0 +1,510 @@
|
||||
import { BaseExecutor } from "./base.ts";
|
||||
import { PROVIDERS } from "../config/constants.ts";
|
||||
import { v4 as uuidv4 } from "uuid";
|
||||
import { refreshKiroToken } from "../services/tokenRefresh.ts";
|
||||
|
||||
// ── CRC32 lookup table (IEEE polynomial, no dependency) ──
|
||||
const CRC32_TABLE = new Uint32Array(256);
|
||||
for (let i = 0; i < 256; i++) {
|
||||
let c = i;
|
||||
for (let j = 0; j < 8; j++) {
|
||||
c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
|
||||
}
|
||||
CRC32_TABLE[i] = c >>> 0;
|
||||
}
|
||||
|
||||
function crc32(buf) {
|
||||
let crc = 0xffffffff;
|
||||
for (let i = 0; i < buf.length; i++) {
|
||||
crc = CRC32_TABLE[(crc ^ buf[i]) & 0xff] ^ (crc >>> 8);
|
||||
}
|
||||
return (crc ^ 0xffffffff) >>> 0;
|
||||
}
|
||||
|
||||
/**
|
||||
* KiroExecutor - Executor for Kiro AI (AWS CodeWhisperer)
|
||||
* Uses AWS CodeWhisperer streaming API with AWS EventStream binary format
|
||||
*/
|
||||
export class KiroExecutor extends BaseExecutor {
|
||||
constructor() {
|
||||
super("kiro", PROVIDERS.kiro);
|
||||
}
|
||||
|
||||
buildHeaders(credentials, stream = true) {
|
||||
const headers = {
|
||||
...this.config.headers,
|
||||
"Amz-Sdk-Request": "attempt=1; max=3",
|
||||
"Amz-Sdk-Invocation-Id": uuidv4(),
|
||||
};
|
||||
|
||||
if (credentials.accessToken) {
|
||||
headers["Authorization"] = `Bearer ${credentials.accessToken}`;
|
||||
}
|
||||
|
||||
return headers;
|
||||
}
|
||||
|
||||
transformRequest(model, body, stream, credentials) {
|
||||
return body;
|
||||
}
|
||||
|
||||
/**
|
||||
* Custom execute for Kiro - handles AWS EventStream binary response
|
||||
*/
|
||||
async execute({ model, body, stream, credentials, signal, log }) {
|
||||
const url = this.buildUrl(model, stream, 0);
|
||||
const headers = this.buildHeaders(credentials, stream);
|
||||
const transformedBody = this.transformRequest(model, body, stream, credentials);
|
||||
|
||||
const response = await fetch(url, {
|
||||
method: "POST",
|
||||
headers,
|
||||
body: JSON.stringify(transformedBody),
|
||||
signal,
|
||||
});
|
||||
|
||||
if (!response.ok) {
|
||||
return { response, url, headers, transformedBody };
|
||||
}
|
||||
|
||||
// For Kiro, we need to transform the binary EventStream to SSE
|
||||
// Create a TransformStream to convert binary to SSE text
|
||||
const transformedResponse = this.transformEventStreamToSSE(response, model);
|
||||
|
||||
return { response: transformedResponse, url, headers, transformedBody };
|
||||
}
|
||||
|
||||
/**
|
||||
* Transform AWS EventStream binary response to SSE text stream
|
||||
* Using TransformStream instead of ReadableStream.pull() to avoid Workers timeout
|
||||
*/
|
||||
transformEventStreamToSSE(response, model) {
|
||||
let buffer = new Uint8Array(0);
|
||||
let chunkIndex = 0;
|
||||
const responseId = `chatcmpl-${Date.now()}`;
|
||||
const created = Math.floor(Date.now() / 1000);
|
||||
const state: Record<string, any> = { endDetected: false,
|
||||
finishEmitted: false,
|
||||
hasToolCalls: false,
|
||||
toolCallIndex: 0,
|
||||
seenToolIds: new Map(),
|
||||
};
|
||||
|
||||
const transformStream = new TransformStream({
|
||||
async transform(chunk, controller) {
|
||||
// Append to buffer
|
||||
const newBuffer = new Uint8Array(buffer.length + chunk.length);
|
||||
newBuffer.set(buffer);
|
||||
newBuffer.set(chunk, buffer.length);
|
||||
buffer = newBuffer;
|
||||
|
||||
// Parse events from buffer
|
||||
let iterations = 0;
|
||||
const maxIterations = 1000;
|
||||
while (buffer.length >= 16 && iterations < maxIterations) {
|
||||
iterations++;
|
||||
const view = new DataView(buffer.buffer, buffer.byteOffset);
|
||||
const totalLength = view.getUint32(0, false);
|
||||
|
||||
if (totalLength < 16 || totalLength > buffer.length || buffer.length < totalLength) break;
|
||||
|
||||
const eventData = buffer.slice(0, totalLength);
|
||||
buffer = buffer.slice(totalLength);
|
||||
|
||||
const event = parseEventFrame(eventData);
|
||||
if (!event) continue;
|
||||
|
||||
const eventType = event.headers[":event-type"] || "";
|
||||
|
||||
// Track total content length for token estimation
|
||||
if (!state.totalContentLength) state.totalContentLength = 0;
|
||||
if (!state.contextUsagePercentage) state.contextUsagePercentage = 0;
|
||||
|
||||
// Handle assistantResponseEvent
|
||||
if (eventType === "assistantResponseEvent" && event.payload?.content) {
|
||||
const content = event.payload.content;
|
||||
state.totalContentLength += content.length;
|
||||
|
||||
const chunk: Record<string, any> = {
|
||||
id: responseId,
|
||||
object: "chat.completion.chunk",
|
||||
created,
|
||||
model,
|
||||
choices: [
|
||||
{
|
||||
index: 0,
|
||||
delta: chunkIndex === 0 ? { role: "assistant", content } : { content },
|
||||
finish_reason: null,
|
||||
},
|
||||
],
|
||||
};
|
||||
chunkIndex++;
|
||||
controller.enqueue(new TextEncoder().encode(`data: ${JSON.stringify(chunk)}\n\n`));
|
||||
}
|
||||
|
||||
// Handle codeEvent
|
||||
if (eventType === "codeEvent" && event.payload?.content) {
|
||||
const chunk: Record<string, any> = {
|
||||
id: responseId,
|
||||
object: "chat.completion.chunk",
|
||||
created,
|
||||
model,
|
||||
choices: [
|
||||
{
|
||||
index: 0,
|
||||
delta: { content: event.payload.content },
|
||||
finish_reason: null,
|
||||
},
|
||||
],
|
||||
};
|
||||
chunkIndex++;
|
||||
controller.enqueue(new TextEncoder().encode(`data: ${JSON.stringify(chunk)}\n\n`));
|
||||
}
|
||||
|
||||
// Handle toolUseEvent
|
||||
if (eventType === "toolUseEvent" && event.payload) {
|
||||
state.hasToolCalls = true;
|
||||
const toolUse = event.payload;
|
||||
const toolUses = Array.isArray(toolUse) ? toolUse : [toolUse];
|
||||
|
||||
for (const singleToolUse of toolUses) {
|
||||
const toolCallId = singleToolUse.toolUseId || `call_${Date.now()}`;
|
||||
const toolName = singleToolUse.name || "";
|
||||
const toolInput = singleToolUse.input;
|
||||
|
||||
let toolIndex;
|
||||
const isNewTool = !state.seenToolIds.has(toolCallId);
|
||||
|
||||
if (isNewTool) {
|
||||
toolIndex = state.toolCallIndex++;
|
||||
state.seenToolIds.set(toolCallId, toolIndex);
|
||||
|
||||
const startChunk = {
|
||||
id: responseId,
|
||||
object: "chat.completion.chunk",
|
||||
created,
|
||||
model,
|
||||
choices: [
|
||||
{
|
||||
index: 0,
|
||||
delta: {
|
||||
...(chunkIndex === 0 ? { role: "assistant" } : {}),
|
||||
tool_calls: [
|
||||
{
|
||||
index: toolIndex,
|
||||
id: toolCallId,
|
||||
type: "function",
|
||||
function: {
|
||||
name: toolName,
|
||||
arguments: "",
|
||||
},
|
||||
},
|
||||
],
|
||||
},
|
||||
finish_reason: null,
|
||||
},
|
||||
],
|
||||
};
|
||||
chunkIndex++;
|
||||
controller.enqueue(
|
||||
new TextEncoder().encode(`data: ${JSON.stringify(startChunk)}\n\n`)
|
||||
);
|
||||
} else {
|
||||
toolIndex = state.seenToolIds.get(toolCallId);
|
||||
}
|
||||
|
||||
if (toolInput !== undefined) {
|
||||
let argumentsStr;
|
||||
|
||||
if (typeof toolInput === "string") {
|
||||
argumentsStr = toolInput;
|
||||
} else if (typeof toolInput === "object") {
|
||||
argumentsStr = JSON.stringify(toolInput);
|
||||
} else {
|
||||
continue;
|
||||
}
|
||||
|
||||
const argsChunk = {
|
||||
id: responseId,
|
||||
object: "chat.completion.chunk",
|
||||
created,
|
||||
model,
|
||||
choices: [
|
||||
{
|
||||
index: 0,
|
||||
delta: {
|
||||
tool_calls: [
|
||||
{
|
||||
index: toolIndex,
|
||||
function: {
|
||||
arguments: argumentsStr,
|
||||
},
|
||||
},
|
||||
],
|
||||
},
|
||||
finish_reason: null,
|
||||
},
|
||||
],
|
||||
};
|
||||
chunkIndex++;
|
||||
controller.enqueue(
|
||||
new TextEncoder().encode(`data: ${JSON.stringify(argsChunk)}\n\n`)
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Handle messageStopEvent
|
||||
if (eventType === "messageStopEvent") {
|
||||
const chunk: Record<string, any> = {
|
||||
id: responseId,
|
||||
object: "chat.completion.chunk",
|
||||
created,
|
||||
model,
|
||||
choices: [
|
||||
{
|
||||
index: 0,
|
||||
delta: {},
|
||||
finish_reason: state.hasToolCalls ? "tool_calls" : "stop",
|
||||
},
|
||||
],
|
||||
};
|
||||
state.finishEmitted = true;
|
||||
controller.enqueue(new TextEncoder().encode(`data: ${JSON.stringify(chunk)}\n\n`));
|
||||
}
|
||||
|
||||
// Handle contextUsageEvent to extract contextUsagePercentage
|
||||
if (eventType === "contextUsageEvent" && event.payload?.contextUsagePercentage) {
|
||||
state.contextUsagePercentage = event.payload.contextUsagePercentage;
|
||||
// Mark that we received context usage event
|
||||
state.hasContextUsage = true;
|
||||
}
|
||||
|
||||
// Handle meteringEvent - mark that we received it
|
||||
if (eventType === "meteringEvent") {
|
||||
state.hasMeteringEvent = true;
|
||||
}
|
||||
|
||||
// Handle metricsEvent for token usage
|
||||
if (eventType === "metricsEvent") {
|
||||
// Extract usage data from metricsEvent payload
|
||||
const metrics = event.payload?.metricsEvent || event.payload;
|
||||
if (metrics && typeof metrics === "object") {
|
||||
const inputTokens = metrics.inputTokens || 0;
|
||||
const outputTokens = metrics.outputTokens || 0;
|
||||
|
||||
if (inputTokens > 0 || outputTokens > 0) {
|
||||
state.usage = {
|
||||
prompt_tokens: inputTokens,
|
||||
completion_tokens: outputTokens,
|
||||
total_tokens: inputTokens + outputTokens,
|
||||
};
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Emit final chunk only after receiving BOTH meteringEvent AND contextUsageEvent
|
||||
if (state.hasMeteringEvent && state.hasContextUsage && !state.finishEmitted) {
|
||||
state.finishEmitted = true;
|
||||
|
||||
// Estimate tokens if not available from events
|
||||
if (!state.usage) {
|
||||
// Estimate output tokens from content length
|
||||
const estimatedOutputTokens =
|
||||
state.totalContentLength > 0
|
||||
? Math.max(1, Math.floor(state.totalContentLength / 4))
|
||||
: 0;
|
||||
|
||||
// Estimate input tokens from contextUsagePercentage
|
||||
// Kiro models typically have 200k context window
|
||||
const estimatedInputTokens =
|
||||
state.contextUsagePercentage > 0
|
||||
? Math.floor((state.contextUsagePercentage * 200000) / 100)
|
||||
: 0;
|
||||
|
||||
state.usage = {
|
||||
prompt_tokens: estimatedInputTokens,
|
||||
completion_tokens: estimatedOutputTokens,
|
||||
total_tokens: estimatedInputTokens + estimatedOutputTokens,
|
||||
};
|
||||
}
|
||||
|
||||
const finishChunk: Record<string, any> = {
|
||||
id: responseId,
|
||||
object: "chat.completion.chunk",
|
||||
created,
|
||||
model,
|
||||
choices: [
|
||||
{
|
||||
index: 0,
|
||||
delta: {},
|
||||
finish_reason: state.hasToolCalls ? "tool_calls" : "stop",
|
||||
},
|
||||
],
|
||||
};
|
||||
|
||||
// Include usage in final chunk if available
|
||||
if (state.usage) {
|
||||
finishChunk.usage = state.usage;
|
||||
}
|
||||
|
||||
controller.enqueue(
|
||||
new TextEncoder().encode(`data: ${JSON.stringify(finishChunk)}\n\n`)
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
if (iterations >= maxIterations) {
|
||||
console.warn("[Kiro] Max iterations reached in event parsing");
|
||||
}
|
||||
},
|
||||
|
||||
flush(controller) {
|
||||
// Emit finish chunk if not already sent
|
||||
if (!state.finishEmitted) {
|
||||
state.finishEmitted = true;
|
||||
const finishChunk = {
|
||||
id: responseId,
|
||||
object: "chat.completion.chunk",
|
||||
created,
|
||||
model,
|
||||
choices: [
|
||||
{
|
||||
index: 0,
|
||||
delta: {},
|
||||
finish_reason: state.hasToolCalls ? "tool_calls" : "stop",
|
||||
},
|
||||
],
|
||||
};
|
||||
controller.enqueue(new TextEncoder().encode(`data: ${JSON.stringify(finishChunk)}\n\n`));
|
||||
}
|
||||
|
||||
// Send final done message
|
||||
controller.enqueue(new TextEncoder().encode("data: [DONE]\n\n"));
|
||||
},
|
||||
});
|
||||
|
||||
// Pipe response body through transform stream
|
||||
const transformedStream = response.body.pipeThrough(transformStream);
|
||||
|
||||
return new Response(transformedStream, {
|
||||
status: response.status,
|
||||
statusText: response.statusText,
|
||||
headers: {
|
||||
"Content-Type": "text/event-stream",
|
||||
"Cache-Control": "no-cache",
|
||||
Connection: "keep-alive",
|
||||
},
|
||||
});
|
||||
}
|
||||
|
||||
async refreshCredentials(credentials, log) {
|
||||
if (!credentials.refreshToken) return null;
|
||||
|
||||
try {
|
||||
// Use centralized refreshKiroToken function (handles both AWS SSO OIDC and Social Auth)
|
||||
const result = await refreshKiroToken(
|
||||
credentials.refreshToken,
|
||||
credentials.providerSpecificData,
|
||||
log
|
||||
);
|
||||
|
||||
return result;
|
||||
} catch (error) {
|
||||
log?.error?.("TOKEN", `Kiro refresh error: ${error.message}`);
|
||||
return null;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Parse AWS EventStream frame
|
||||
*/
|
||||
function parseEventFrame(data) {
|
||||
try {
|
||||
const view = new DataView(data.buffer, data.byteOffset);
|
||||
const totalLength = view.getUint32(0, false);
|
||||
const headersLength = view.getUint32(4, false);
|
||||
|
||||
// ── CRC32 validation ──
|
||||
// Prelude CRC covers bytes [0..7] (totalLength + headersLength)
|
||||
const preludeCRC = view.getUint32(8, false);
|
||||
const computedPreludeCRC = crc32(data.slice(0, 8));
|
||||
if (preludeCRC !== computedPreludeCRC) {
|
||||
console.warn(
|
||||
`[Kiro] Prelude CRC mismatch: expected ${preludeCRC}, got ${computedPreludeCRC} — skipping corrupted frame`
|
||||
);
|
||||
return null;
|
||||
}
|
||||
|
||||
// Message CRC covers bytes [0..totalLength-5] (everything except the CRC itself)
|
||||
const messageCRC = view.getUint32(data.length - 4, false);
|
||||
const computedMessageCRC = crc32(data.slice(0, data.length - 4));
|
||||
if (messageCRC !== computedMessageCRC) {
|
||||
console.warn(
|
||||
`[Kiro] Message CRC mismatch: expected ${messageCRC}, got ${computedMessageCRC} — skipping corrupted frame`
|
||||
);
|
||||
return null;
|
||||
}
|
||||
// Parse headers
|
||||
const headers = {};
|
||||
let offset = 12; // After prelude
|
||||
const headerEnd = 12 + headersLength;
|
||||
|
||||
while (offset < headerEnd && offset < data.length) {
|
||||
const nameLen = data[offset];
|
||||
offset++;
|
||||
if (offset + nameLen > data.length) break;
|
||||
|
||||
const name = new TextDecoder().decode(data.slice(offset, offset + nameLen));
|
||||
offset += nameLen;
|
||||
|
||||
const headerType = data[offset];
|
||||
offset++;
|
||||
|
||||
if (headerType === 7) {
|
||||
// String type
|
||||
const valueLen = (data[offset] << 8) | data[offset + 1];
|
||||
offset += 2;
|
||||
if (offset + valueLen > data.length) break;
|
||||
|
||||
const value = new TextDecoder().decode(data.slice(offset, offset + valueLen));
|
||||
offset += valueLen;
|
||||
headers[name] = value;
|
||||
} else {
|
||||
break;
|
||||
}
|
||||
}
|
||||
|
||||
// Parse payload
|
||||
const payloadStart = 12 + headersLength;
|
||||
const payloadEnd = data.length - 4; // Exclude message CRC
|
||||
|
||||
let payload = null;
|
||||
if (payloadEnd > payloadStart) {
|
||||
const payloadStr = new TextDecoder().decode(data.slice(payloadStart, payloadEnd));
|
||||
|
||||
// Skip empty or whitespace-only payloads
|
||||
if (!payloadStr || !payloadStr.trim()) {
|
||||
return { headers, payload: null };
|
||||
}
|
||||
|
||||
try {
|
||||
payload = JSON.parse(payloadStr);
|
||||
} catch (parseError) {
|
||||
// Log parse error for debugging
|
||||
console.warn(
|
||||
`[Kiro] Failed to parse payload: ${parseError.message} | payload: ${payloadStr.substring(0, 100)}`
|
||||
);
|
||||
payload = { raw: payloadStr };
|
||||
}
|
||||
}
|
||||
|
||||
return { headers, payload };
|
||||
} catch (err) {
|
||||
console.warn(`[Kiro] Frame parse error: ${err.message}`);
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
export default KiroExecutor;
|
||||
174
open-sse/handlers/audioSpeech.ts
Normal file
174
open-sse/handlers/audioSpeech.ts
Normal file
@@ -0,0 +1,174 @@
|
||||
/**
|
||||
* Audio Speech Handler (TTS)
|
||||
*
|
||||
* Handles POST /v1/audio/speech (OpenAI TTS API format).
|
||||
* Returns audio binary stream.
|
||||
*
|
||||
* Supported provider formats:
|
||||
* - OpenAI: standard JSON → audio stream proxy
|
||||
* - Hyperbolic: POST { text } → { audio: base64 }
|
||||
* - Deepgram: POST { text } with model via query param, Token auth
|
||||
*/
|
||||
|
||||
import { getSpeechProvider, parseSpeechModel } from "../config/audioRegistry.ts";
|
||||
import { errorResponse } from "../utils/error.ts";
|
||||
|
||||
/**
|
||||
* Build auth header for a speech provider
|
||||
*/
|
||||
function buildAuthHeader(providerConfig, token) {
|
||||
if (providerConfig.authHeader === "token") {
|
||||
return { Authorization: `Token ${token}` };
|
||||
}
|
||||
return { Authorization: `Bearer ${token}` };
|
||||
}
|
||||
|
||||
/**
|
||||
* Handle Hyperbolic TTS (returns base64 audio in JSON)
|
||||
*/
|
||||
async function handleHyperbolicSpeech(providerConfig, body, token) {
|
||||
const res = await fetch(providerConfig.baseUrl, {
|
||||
method: "POST",
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
...buildAuthHeader(providerConfig, token),
|
||||
},
|
||||
body: JSON.stringify({ text: body.input }),
|
||||
});
|
||||
|
||||
if (!res.ok) {
|
||||
const errText = await res.text();
|
||||
return new Response(errText, {
|
||||
status: res.status,
|
||||
headers: { "Content-Type": "application/json", "Access-Control-Allow-Origin": "*" },
|
||||
});
|
||||
}
|
||||
|
||||
const data = await res.json();
|
||||
// Hyperbolic returns { audio: "<base64>" }, decode to binary
|
||||
const audioBuffer = Uint8Array.from(atob(data.audio), (c) => c.charCodeAt(0));
|
||||
|
||||
return new Response(audioBuffer, {
|
||||
status: 200,
|
||||
headers: {
|
||||
"Content-Type": "audio/mpeg",
|
||||
"Access-Control-Allow-Origin": "*",
|
||||
},
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Handle Deepgram TTS (model via query param, Token auth, returns binary audio)
|
||||
*/
|
||||
async function handleDeepgramSpeech(providerConfig, body, modelId, token) {
|
||||
const url = new URL(providerConfig.baseUrl);
|
||||
url.searchParams.set("model", modelId);
|
||||
|
||||
const res = await fetch(url.toString(), {
|
||||
method: "POST",
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
...buildAuthHeader(providerConfig, token),
|
||||
},
|
||||
body: JSON.stringify({ text: body.input }),
|
||||
});
|
||||
|
||||
if (!res.ok) {
|
||||
const errText = await res.text();
|
||||
return new Response(errText, {
|
||||
status: res.status,
|
||||
headers: { "Content-Type": "application/json", "Access-Control-Allow-Origin": "*" },
|
||||
});
|
||||
}
|
||||
|
||||
const contentType = res.headers.get("content-type") || "audio/mpeg";
|
||||
return new Response(res.body, {
|
||||
status: 200,
|
||||
headers: {
|
||||
"Content-Type": contentType,
|
||||
"Access-Control-Allow-Origin": "*",
|
||||
"Transfer-Encoding": "chunked",
|
||||
},
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Handle audio speech (TTS) request
|
||||
*
|
||||
* @param {Object} options
|
||||
* @param {Object} options.body - JSON request body { model, input, voice, ... }
|
||||
* @param {Object} options.credentials - Provider credentials { apiKey }
|
||||
* @returns {Response}
|
||||
*/
|
||||
/** @returns {Promise<any>} */
|
||||
export async function handleAudioSpeech({ body, credentials }) {
|
||||
if (!body.model) {
|
||||
return errorResponse(400, "model is required");
|
||||
}
|
||||
if (!body.input) {
|
||||
return errorResponse(400, "input is required");
|
||||
}
|
||||
|
||||
const { provider: providerId, model: modelId } = parseSpeechModel(body.model);
|
||||
const providerConfig = providerId ? getSpeechProvider(providerId) : null;
|
||||
|
||||
if (!providerConfig) {
|
||||
return errorResponse(
|
||||
400,
|
||||
`No speech provider found for model "${body.model}". Available: openai, hyperbolic, deepgram`
|
||||
);
|
||||
}
|
||||
|
||||
const token = credentials?.apiKey || credentials?.accessToken;
|
||||
if (!token) {
|
||||
return errorResponse(401, `No credentials for speech provider: ${providerId}`);
|
||||
}
|
||||
|
||||
try {
|
||||
// Route to provider-specific handler
|
||||
if (providerConfig.format === "hyperbolic") {
|
||||
return handleHyperbolicSpeech(providerConfig, body, token);
|
||||
}
|
||||
|
||||
if (providerConfig.format === "deepgram") {
|
||||
return handleDeepgramSpeech(providerConfig, body, modelId, token);
|
||||
}
|
||||
|
||||
// Default: OpenAI-compatible JSON → audio stream proxy
|
||||
const res = await fetch(providerConfig.baseUrl, {
|
||||
method: "POST",
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
...buildAuthHeader(providerConfig, token),
|
||||
},
|
||||
body: JSON.stringify({
|
||||
model: modelId,
|
||||
input: body.input,
|
||||
voice: body.voice || "alloy",
|
||||
response_format: body.response_format || "mp3",
|
||||
speed: body.speed || 1.0,
|
||||
}),
|
||||
});
|
||||
|
||||
if (!res.ok) {
|
||||
const errText = await res.text();
|
||||
return new Response(errText, {
|
||||
status: res.status,
|
||||
headers: { "Content-Type": "application/json", "Access-Control-Allow-Origin": "*" },
|
||||
});
|
||||
}
|
||||
|
||||
// Stream audio response back to client
|
||||
const contentType = res.headers.get("content-type") || "audio/mpeg";
|
||||
return new Response(res.body, {
|
||||
status: 200,
|
||||
headers: {
|
||||
"Content-Type": contentType,
|
||||
"Access-Control-Allow-Origin": "*",
|
||||
"Transfer-Encoding": "chunked",
|
||||
},
|
||||
});
|
||||
} catch (err) {
|
||||
return errorResponse(500, `Speech request failed: ${err.message}`);
|
||||
}
|
||||
}
|
||||
227
open-sse/handlers/audioTranscription.ts
Normal file
227
open-sse/handlers/audioTranscription.ts
Normal file
@@ -0,0 +1,227 @@
|
||||
/**
|
||||
* Audio Transcription Handler
|
||||
*
|
||||
* Handles POST /v1/audio/transcriptions (Whisper API format).
|
||||
* Proxies multipart/form-data to upstream providers.
|
||||
*
|
||||
* Supported provider formats:
|
||||
* - OpenAI/Groq: standard multipart form-data proxy
|
||||
* - Deepgram: raw binary audio POST with model via query param
|
||||
* - AssemblyAI: async workflow (upload → submit → poll)
|
||||
*/
|
||||
|
||||
import { getTranscriptionProvider, parseTranscriptionModel } from "../config/audioRegistry.ts";
|
||||
import { errorResponse } from "../utils/error.ts";
|
||||
|
||||
/**
|
||||
* Build auth header for a transcription provider
|
||||
*/
|
||||
function buildAuthHeader(providerConfig, token) {
|
||||
if (providerConfig.authHeader === "token") {
|
||||
return { Authorization: `Token ${token}` };
|
||||
}
|
||||
return { Authorization: `Bearer ${token}` };
|
||||
}
|
||||
|
||||
/**
|
||||
* Handle Deepgram transcription (raw binary audio, model via query param)
|
||||
*/
|
||||
async function handleDeepgramTranscription(providerConfig, file, modelId, token) {
|
||||
const url = new URL(providerConfig.baseUrl);
|
||||
url.searchParams.set("model", modelId);
|
||||
url.searchParams.set("smart_format", "true");
|
||||
|
||||
const arrayBuffer = await file.arrayBuffer();
|
||||
|
||||
const res = await fetch(url.toString(), {
|
||||
method: "POST",
|
||||
headers: {
|
||||
...buildAuthHeader(providerConfig, token),
|
||||
"Content-Type": file.type || "audio/wav",
|
||||
},
|
||||
body: arrayBuffer,
|
||||
});
|
||||
|
||||
if (!res.ok) {
|
||||
const errText = await res.text();
|
||||
return new Response(errText, {
|
||||
status: res.status,
|
||||
headers: { "Content-Type": "application/json", "Access-Control-Allow-Origin": "*" },
|
||||
});
|
||||
}
|
||||
|
||||
const data = await res.json();
|
||||
// Transform Deepgram response to OpenAI Whisper format
|
||||
const text = data.results?.channels?.[0]?.alternatives?.[0]?.transcript || "";
|
||||
|
||||
return Response.json({ text }, { headers: { "Access-Control-Allow-Origin": "*" } });
|
||||
}
|
||||
|
||||
/**
|
||||
* Handle AssemblyAI transcription (async: upload file → submit → poll)
|
||||
*/
|
||||
async function handleAssemblyAITranscription(providerConfig, file, modelId, token) {
|
||||
const authHeaders = buildAuthHeader(providerConfig, token);
|
||||
|
||||
// Step 1: Upload the audio file
|
||||
const arrayBuffer = await file.arrayBuffer();
|
||||
const uploadRes = await fetch("https://api.assemblyai.com/v2/upload", {
|
||||
method: "POST",
|
||||
headers: {
|
||||
...authHeaders,
|
||||
"Content-Type": "application/octet-stream",
|
||||
},
|
||||
body: arrayBuffer,
|
||||
});
|
||||
|
||||
if (!uploadRes.ok) {
|
||||
const errText = await uploadRes.text();
|
||||
return new Response(errText, {
|
||||
status: uploadRes.status,
|
||||
headers: { "Content-Type": "application/json", "Access-Control-Allow-Origin": "*" },
|
||||
});
|
||||
}
|
||||
|
||||
const { upload_url } = await uploadRes.json();
|
||||
|
||||
// Step 2: Submit transcription request
|
||||
const submitRes = await fetch(providerConfig.baseUrl, {
|
||||
method: "POST",
|
||||
headers: {
|
||||
...authHeaders,
|
||||
"Content-Type": "application/json",
|
||||
},
|
||||
body: JSON.stringify({
|
||||
audio_url: upload_url,
|
||||
speech_models: [modelId],
|
||||
language_detection: true,
|
||||
}),
|
||||
});
|
||||
|
||||
if (!submitRes.ok) {
|
||||
const errText = await submitRes.text();
|
||||
return new Response(errText, {
|
||||
status: submitRes.status,
|
||||
headers: { "Content-Type": "application/json", "Access-Control-Allow-Origin": "*" },
|
||||
});
|
||||
}
|
||||
|
||||
const { id: transcriptId } = await submitRes.json();
|
||||
|
||||
// Step 3: Poll for completion (max 120s)
|
||||
const pollUrl = `${providerConfig.baseUrl}/${transcriptId}`;
|
||||
const maxWait = 120_000;
|
||||
const start = Date.now();
|
||||
|
||||
while (Date.now() - start < maxWait) {
|
||||
await new Promise((r) => setTimeout(r, 2000));
|
||||
|
||||
const pollRes = await fetch(pollUrl, { headers: authHeaders });
|
||||
if (!pollRes.ok) continue;
|
||||
|
||||
const result = await pollRes.json();
|
||||
|
||||
if (result.status === "completed") {
|
||||
return Response.json(
|
||||
{ text: result.text || "" },
|
||||
{ headers: { "Access-Control-Allow-Origin": "*" } }
|
||||
);
|
||||
}
|
||||
|
||||
if (result.status === "error") {
|
||||
return errorResponse(500, result.error || "AssemblyAI transcription failed");
|
||||
}
|
||||
}
|
||||
|
||||
return errorResponse(504, "AssemblyAI transcription timed out after 120s");
|
||||
}
|
||||
|
||||
/**
|
||||
* Handle audio transcription request
|
||||
*
|
||||
* @param {Object} options
|
||||
* @param {FormData} options.formData - Multipart form data with file + model
|
||||
* @param {Object} options.credentials - Provider credentials { apiKey }
|
||||
* @returns {Response}
|
||||
*/
|
||||
/** @returns {Promise<any>} */
|
||||
export async function handleAudioTranscription({ formData, credentials }) {
|
||||
const model = formData.get("model");
|
||||
if (!model) {
|
||||
return errorResponse(400, "model is required");
|
||||
}
|
||||
|
||||
const file = formData.get("file");
|
||||
if (!file) {
|
||||
return errorResponse(400, "file is required");
|
||||
}
|
||||
|
||||
const { provider: providerId, model: modelId } = parseTranscriptionModel(model);
|
||||
const providerConfig = providerId ? getTranscriptionProvider(providerId) : null;
|
||||
|
||||
if (!providerConfig) {
|
||||
return errorResponse(
|
||||
400,
|
||||
`No transcription provider found for model "${model}". Available: openai, groq, deepgram, assemblyai`
|
||||
);
|
||||
}
|
||||
|
||||
const token = credentials?.apiKey || credentials?.accessToken;
|
||||
if (!token) {
|
||||
return errorResponse(401, `No credentials for transcription provider: ${providerId}`);
|
||||
}
|
||||
|
||||
// Route to provider-specific handler
|
||||
if (providerConfig.format === "deepgram") {
|
||||
return handleDeepgramTranscription(providerConfig, file, modelId, token);
|
||||
}
|
||||
|
||||
if (providerConfig.format === "assemblyai") {
|
||||
return handleAssemblyAITranscription(providerConfig, file, modelId, token);
|
||||
}
|
||||
|
||||
// Default: OpenAI/Groq-compatible multipart proxy
|
||||
const upstreamForm = new FormData();
|
||||
upstreamForm.append("file", /** @type {Blob} */ (file), /** @type {any} */ (file).name || "audio.wav");
|
||||
upstreamForm.append("model", modelId);
|
||||
|
||||
// Forward optional parameters
|
||||
for (const key of [
|
||||
"language",
|
||||
"prompt",
|
||||
"response_format",
|
||||
"temperature",
|
||||
"timestamp_granularities[]",
|
||||
]) {
|
||||
const val = formData.get(key);
|
||||
if (val !== null && val !== undefined) {
|
||||
upstreamForm.append(key, /** @type {string} */ (val));
|
||||
}
|
||||
}
|
||||
|
||||
try {
|
||||
const res = await fetch(providerConfig.baseUrl, {
|
||||
method: "POST",
|
||||
headers: buildAuthHeader(providerConfig, token),
|
||||
body: upstreamForm,
|
||||
});
|
||||
|
||||
if (!res.ok) {
|
||||
const errText = await res.text();
|
||||
return new Response(errText, {
|
||||
status: res.status,
|
||||
headers: { "Content-Type": "application/json", "Access-Control-Allow-Origin": "*" },
|
||||
});
|
||||
}
|
||||
|
||||
const data = await res.text();
|
||||
const contentType = res.headers.get("content-type") || "application/json";
|
||||
|
||||
return new Response(data, {
|
||||
status: 200,
|
||||
headers: { "Content-Type": contentType, "Access-Control-Allow-Origin": "*" },
|
||||
});
|
||||
} catch (err) {
|
||||
return errorResponse(500, `Transcription request failed: ${err.message}`);
|
||||
}
|
||||
}
|
||||
635
open-sse/handlers/chatCore.ts
Normal file
635
open-sse/handlers/chatCore.ts
Normal file
@@ -0,0 +1,635 @@
|
||||
import { detectFormat, getTargetFormat } from "../services/provider.ts";
|
||||
import { translateRequest, needsTranslation } from "../translator/index.ts";
|
||||
import { FORMATS } from "../translator/formats.ts";
|
||||
import {
|
||||
createSSETransformStreamWithLogger,
|
||||
createPassthroughStreamWithLogger,
|
||||
COLORS,
|
||||
} from "../utils/stream.ts";
|
||||
import { createStreamController, pipeWithDisconnect } from "../utils/streamHandler.ts";
|
||||
import { addBufferToUsage, filterUsageForFormat, estimateUsage } from "../utils/usageTracking.ts";
|
||||
import { refreshWithRetry } from "../services/tokenRefresh.ts";
|
||||
import { createRequestLogger } from "../utils/requestLogger.ts";
|
||||
import { getModelTargetFormat, PROVIDER_ID_TO_ALIAS } from "../config/providerModels.ts";
|
||||
import { createErrorResult, parseUpstreamError, formatProviderError } from "../utils/error.ts";
|
||||
import { HTTP_STATUS } from "../config/constants.ts";
|
||||
import { handleBypassRequest } from "../utils/bypassHandler.ts";
|
||||
import {
|
||||
saveRequestUsage,
|
||||
trackPendingRequest,
|
||||
appendRequestLog,
|
||||
saveCallLog,
|
||||
} from "@/lib/usageDb";
|
||||
import { getExecutor } from "../executors/index.ts";
|
||||
import { translateNonStreamingResponse } from "./responseTranslator.ts";
|
||||
import { extractUsageFromResponse } from "./usageExtractor.ts";
|
||||
import { parseSSEToOpenAIResponse, parseSSEToResponsesOutput } from "./sseParser.ts";
|
||||
import {
|
||||
withRateLimit,
|
||||
updateFromHeaders,
|
||||
initializeRateLimits,
|
||||
} from "../services/rateLimitManager.ts";
|
||||
import {
|
||||
generateSignature,
|
||||
getCachedResponse,
|
||||
setCachedResponse,
|
||||
isCacheable,
|
||||
} from "@/lib/semanticCache";
|
||||
import { getIdempotencyKey, checkIdempotency, saveIdempotency } from "@/lib/idempotencyLayer";
|
||||
import { createProgressTransform, wantsProgress } from "../utils/progressTracker.ts";
|
||||
|
||||
/**
|
||||
* Core chat handler - shared between SSE and Worker
|
||||
* Returns { success, response, status, error } for caller to handle fallback
|
||||
* @param {object} options
|
||||
* @param {object} options.body - Request body
|
||||
* @param {object} options.modelInfo - { provider, model }
|
||||
* @param {object} options.credentials - Provider credentials
|
||||
* @param {object} options.log - Logger instance (optional)
|
||||
* @param {function} options.onCredentialsRefreshed - Callback when credentials are refreshed
|
||||
* @param {function} options.onRequestSuccess - Callback when request succeeds (to clear error status)
|
||||
* @param {function} options.onDisconnect - Callback when client disconnects
|
||||
* @param {string} options.connectionId - Connection ID for usage tracking
|
||||
* @param {object} options.apiKeyInfo - API key metadata for usage attribution
|
||||
*/
|
||||
/** @param {any} options */
|
||||
export async function handleChatCore({
|
||||
body,
|
||||
modelInfo,
|
||||
credentials,
|
||||
log,
|
||||
onCredentialsRefreshed,
|
||||
onRequestSuccess,
|
||||
onDisconnect,
|
||||
clientRawRequest,
|
||||
connectionId,
|
||||
apiKeyInfo = null,
|
||||
userAgent,
|
||||
comboName,
|
||||
}) {
|
||||
const { provider, model } = modelInfo;
|
||||
const startTime = Date.now();
|
||||
|
||||
// ── Phase 9.2: Idempotency check ──
|
||||
const idempotencyKey = getIdempotencyKey(clientRawRequest?.headers);
|
||||
const cachedIdemp = checkIdempotency(idempotencyKey);
|
||||
if (cachedIdemp) {
|
||||
log?.debug?.("IDEMPOTENCY", `Hit for key=${idempotencyKey?.slice(0, 12)}...`);
|
||||
return {
|
||||
success: true,
|
||||
response: new Response(JSON.stringify(cachedIdemp.response), {
|
||||
status: cachedIdemp.status,
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
"Access-Control-Allow-Origin": "*",
|
||||
"X-OmniRoute-Idempotent": "true",
|
||||
},
|
||||
}),
|
||||
};
|
||||
}
|
||||
|
||||
// Initialize rate limit settings from persisted DB (once, lazy)
|
||||
await initializeRateLimits();
|
||||
|
||||
const sourceFormat = detectFormat(body);
|
||||
const endpointPath = (clientRawRequest?.endpoint || "").toLowerCase();
|
||||
const isResponsesEndpoint = endpointPath.endsWith("/responses");
|
||||
|
||||
// Check for bypass patterns (warmup, skip) - return fake response
|
||||
const bypassResponse = handleBypassRequest(body, model, userAgent);
|
||||
if (bypassResponse) {
|
||||
return bypassResponse;
|
||||
}
|
||||
|
||||
// Detect source format and get target format
|
||||
// Model-specific targetFormat takes priority over provider default
|
||||
|
||||
const alias = PROVIDER_ID_TO_ALIAS[provider] || provider;
|
||||
const modelTargetFormat = getModelTargetFormat(alias, model);
|
||||
const targetFormat = modelTargetFormat || getTargetFormat(provider);
|
||||
|
||||
// Default to streaming unless client explicitly sets stream: false
|
||||
const stream = body.stream !== false;
|
||||
|
||||
// ── Phase 9.1: Semantic cache check (non-streaming, temp=0 only) ──
|
||||
if (isCacheable(body, clientRawRequest?.headers)) {
|
||||
const signature = generateSignature(model, body.messages, body.temperature, body.top_p);
|
||||
const cached = getCachedResponse(signature);
|
||||
if (cached) {
|
||||
log?.debug?.("CACHE", `Semantic cache HIT for ${model}`);
|
||||
return {
|
||||
success: true,
|
||||
response: new Response(JSON.stringify(cached), {
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
"Access-Control-Allow-Origin": "*",
|
||||
"X-OmniRoute-Cache": "HIT",
|
||||
},
|
||||
}),
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
// Create request logger for this session: sourceFormat_targetFormat_model
|
||||
const reqLogger = await createRequestLogger(sourceFormat, targetFormat, model);
|
||||
|
||||
// 0. Log client raw request (before any conversion)
|
||||
if (clientRawRequest) {
|
||||
reqLogger.logClientRawRequest(
|
||||
clientRawRequest.endpoint,
|
||||
clientRawRequest.body,
|
||||
clientRawRequest.headers
|
||||
);
|
||||
}
|
||||
|
||||
// 1. Log raw request from client
|
||||
reqLogger.logRawRequest(body);
|
||||
|
||||
log?.debug?.("FORMAT", `${sourceFormat} → ${targetFormat} | stream=${stream}`);
|
||||
|
||||
// Translate request (pass reqLogger for intermediate logging)
|
||||
let translatedBody = body;
|
||||
try {
|
||||
translatedBody = translateRequest(
|
||||
sourceFormat,
|
||||
targetFormat,
|
||||
model,
|
||||
body,
|
||||
stream,
|
||||
credentials,
|
||||
provider,
|
||||
reqLogger
|
||||
);
|
||||
} catch (error) {
|
||||
const parsedStatus = Number(error?.statusCode);
|
||||
const statusCode =
|
||||
Number.isInteger(parsedStatus) && parsedStatus >= 400 && parsedStatus <= 599
|
||||
? parsedStatus
|
||||
: HTTP_STATUS.SERVER_ERROR;
|
||||
const message = error?.message || "Invalid request";
|
||||
const errorType = typeof error?.errorType === "string" ? error.errorType : null;
|
||||
|
||||
log?.warn?.("TRANSLATE", `Request translation failed: ${message}`);
|
||||
|
||||
if (errorType) {
|
||||
return {
|
||||
success: false,
|
||||
status: statusCode,
|
||||
error: message,
|
||||
response: new Response(
|
||||
JSON.stringify({
|
||||
error: {
|
||||
message,
|
||||
type: errorType,
|
||||
code: errorType,
|
||||
},
|
||||
}),
|
||||
{
|
||||
status: statusCode,
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
"Access-Control-Allow-Origin": "*",
|
||||
},
|
||||
}
|
||||
),
|
||||
};
|
||||
}
|
||||
|
||||
return createErrorResult(statusCode, message);
|
||||
}
|
||||
|
||||
// Extract toolNameMap for response translation (Claude OAuth)
|
||||
const toolNameMap = translatedBody._toolNameMap;
|
||||
delete translatedBody._toolNameMap;
|
||||
|
||||
// Update model in body
|
||||
translatedBody.model = model;
|
||||
|
||||
// Get executor for this provider
|
||||
const executor = getExecutor(provider);
|
||||
|
||||
// Track pending request
|
||||
trackPendingRequest(model, provider, connectionId, true);
|
||||
|
||||
// Log start
|
||||
appendRequestLog({ model, provider, connectionId, status: "PENDING" }).catch(() => {});
|
||||
|
||||
const msgCount =
|
||||
translatedBody.messages?.length ||
|
||||
translatedBody.contents?.length ||
|
||||
translatedBody.request?.contents?.length ||
|
||||
0;
|
||||
log?.debug?.("REQUEST", `${provider.toUpperCase()} | ${model} | ${msgCount} msgs`);
|
||||
|
||||
// Create stream controller for disconnect detection
|
||||
const streamController = createStreamController({ onDisconnect, log, provider, model });
|
||||
|
||||
// Execute request using executor (handles URL building, headers, fallback, transform)
|
||||
let providerResponse;
|
||||
let providerUrl;
|
||||
let providerHeaders;
|
||||
let finalBody;
|
||||
|
||||
try {
|
||||
const result = await withRateLimit(provider, connectionId, model, () =>
|
||||
executor.execute({
|
||||
model,
|
||||
body: translatedBody,
|
||||
stream,
|
||||
credentials,
|
||||
signal: streamController.signal,
|
||||
log,
|
||||
})
|
||||
);
|
||||
|
||||
providerResponse = result.response;
|
||||
providerUrl = result.url;
|
||||
providerHeaders = result.headers;
|
||||
finalBody = result.transformedBody;
|
||||
|
||||
// Log target request (final request to provider)
|
||||
reqLogger.logTargetRequest(providerUrl, providerHeaders, finalBody);
|
||||
|
||||
// Update rate limiter from response headers (learn limits dynamically)
|
||||
updateFromHeaders(
|
||||
provider,
|
||||
connectionId,
|
||||
providerResponse.headers,
|
||||
providerResponse.status,
|
||||
model
|
||||
);
|
||||
} catch (error) {
|
||||
trackPendingRequest(model, provider, connectionId, false);
|
||||
appendRequestLog({
|
||||
model,
|
||||
provider,
|
||||
connectionId,
|
||||
status: `FAILED ${error.name === "AbortError" ? 499 : HTTP_STATUS.BAD_GATEWAY}`,
|
||||
}).catch(() => {});
|
||||
saveCallLog({
|
||||
method: "POST",
|
||||
path: clientRawRequest?.endpoint || "/v1/chat/completions",
|
||||
status: error.name === "AbortError" ? 499 : HTTP_STATUS.BAD_GATEWAY,
|
||||
model,
|
||||
provider,
|
||||
connectionId,
|
||||
duration: Date.now() - startTime,
|
||||
requestBody: body,
|
||||
error: error.message,
|
||||
sourceFormat,
|
||||
targetFormat,
|
||||
comboName,
|
||||
apiKeyId: apiKeyInfo?.id || null,
|
||||
apiKeyName: apiKeyInfo?.name || null,
|
||||
}).catch(() => {});
|
||||
if (error.name === "AbortError") {
|
||||
streamController.handleError(error);
|
||||
return createErrorResult(499, "Request aborted");
|
||||
}
|
||||
const errMsg = formatProviderError(error, provider, model, HTTP_STATUS.BAD_GATEWAY);
|
||||
console.log(`${COLORS.red}[ERROR] ${errMsg}${COLORS.reset}`);
|
||||
return createErrorResult(HTTP_STATUS.BAD_GATEWAY, errMsg);
|
||||
}
|
||||
|
||||
// Handle 401/403 - try token refresh using executor
|
||||
if (
|
||||
providerResponse.status === HTTP_STATUS.UNAUTHORIZED ||
|
||||
providerResponse.status === HTTP_STATUS.FORBIDDEN
|
||||
) {
|
||||
const newCredentials = await refreshWithRetry(
|
||||
() => executor.refreshCredentials(credentials, log),
|
||||
3,
|
||||
log
|
||||
);
|
||||
|
||||
if (newCredentials?.accessToken || newCredentials?.copilotToken) {
|
||||
log?.info?.("TOKEN", `${provider.toUpperCase()} | refreshed`);
|
||||
|
||||
// Update credentials
|
||||
Object.assign(credentials, newCredentials);
|
||||
|
||||
// Notify caller about refreshed credentials
|
||||
if (onCredentialsRefreshed && newCredentials) {
|
||||
await onCredentialsRefreshed(newCredentials);
|
||||
}
|
||||
|
||||
// Retry with new credentials
|
||||
try {
|
||||
const retryResult = await executor.execute({
|
||||
model,
|
||||
body: translatedBody,
|
||||
stream,
|
||||
credentials,
|
||||
signal: streamController.signal,
|
||||
log,
|
||||
});
|
||||
|
||||
if (retryResult.response.ok) {
|
||||
providerResponse = retryResult.response;
|
||||
providerUrl = retryResult.url;
|
||||
}
|
||||
} catch (retryError) {
|
||||
log?.warn?.("TOKEN", `${provider.toUpperCase()} | retry after refresh failed`);
|
||||
}
|
||||
} else {
|
||||
log?.warn?.("TOKEN", `${provider.toUpperCase()} | refresh failed`);
|
||||
}
|
||||
}
|
||||
|
||||
// Check provider response - return error info for fallback handling
|
||||
if (!providerResponse.ok) {
|
||||
trackPendingRequest(model, provider, connectionId, false);
|
||||
const { statusCode, message, retryAfterMs } = await parseUpstreamError(
|
||||
providerResponse,
|
||||
provider
|
||||
);
|
||||
appendRequestLog({ model, provider, connectionId, status: `FAILED ${statusCode}` }).catch(
|
||||
() => {}
|
||||
);
|
||||
saveCallLog({
|
||||
method: "POST",
|
||||
path: clientRawRequest?.endpoint || "/v1/chat/completions",
|
||||
status: statusCode,
|
||||
model,
|
||||
provider,
|
||||
connectionId,
|
||||
duration: Date.now() - startTime,
|
||||
requestBody: body,
|
||||
error: message,
|
||||
sourceFormat,
|
||||
targetFormat,
|
||||
comboName,
|
||||
apiKeyId: apiKeyInfo?.id || null,
|
||||
apiKeyName: apiKeyInfo?.name || null,
|
||||
}).catch(() => {});
|
||||
const errMsg = formatProviderError(new Error(message), provider, model, statusCode);
|
||||
console.log(`${COLORS.red}[ERROR] ${errMsg}${COLORS.reset}`);
|
||||
|
||||
// Log Antigravity retry time if available
|
||||
if (retryAfterMs && provider === "antigravity") {
|
||||
const retrySeconds = Math.ceil(retryAfterMs / 1000);
|
||||
log?.debug?.("RETRY", `Antigravity quota reset in ${retrySeconds}s (${retryAfterMs}ms)`);
|
||||
}
|
||||
|
||||
// Log error with full request body for debugging
|
||||
reqLogger.logError(new Error(message), finalBody || translatedBody);
|
||||
|
||||
// Update rate limiter from error response headers
|
||||
updateFromHeaders(provider, connectionId, providerResponse.headers, statusCode, model);
|
||||
|
||||
return createErrorResult(statusCode, errMsg, retryAfterMs);
|
||||
}
|
||||
|
||||
// Non-streaming response
|
||||
if (!stream) {
|
||||
trackPendingRequest(model, provider, connectionId, false);
|
||||
const contentType = (providerResponse.headers.get("content-type") || "").toLowerCase();
|
||||
let responseBody;
|
||||
const rawBody = await providerResponse.text();
|
||||
const looksLikeSSE =
|
||||
contentType.includes("text/event-stream") || /(^|\n)\s*(event|data):/m.test(rawBody);
|
||||
|
||||
if (looksLikeSSE) {
|
||||
// Upstream returned SSE even though stream=false; convert best-effort to JSON.
|
||||
const parsedFromSSE =
|
||||
targetFormat === FORMATS.OPENAI_RESPONSES
|
||||
? parseSSEToResponsesOutput(rawBody, model)
|
||||
: parseSSEToOpenAIResponse(rawBody, model);
|
||||
|
||||
if (!parsedFromSSE) {
|
||||
appendRequestLog({
|
||||
model,
|
||||
provider,
|
||||
connectionId,
|
||||
status: `FAILED ${HTTP_STATUS.BAD_GATEWAY}`,
|
||||
}).catch(() => {});
|
||||
return createErrorResult(
|
||||
HTTP_STATUS.BAD_GATEWAY,
|
||||
"Invalid SSE response for non-streaming request"
|
||||
);
|
||||
}
|
||||
|
||||
responseBody = parsedFromSSE;
|
||||
} else {
|
||||
try {
|
||||
responseBody = rawBody ? JSON.parse(rawBody) : {};
|
||||
} catch {
|
||||
appendRequestLog({
|
||||
model,
|
||||
provider,
|
||||
connectionId,
|
||||
status: `FAILED ${HTTP_STATUS.BAD_GATEWAY}`,
|
||||
}).catch(() => {});
|
||||
return createErrorResult(HTTP_STATUS.BAD_GATEWAY, "Invalid JSON response from provider");
|
||||
}
|
||||
}
|
||||
|
||||
// Notify success - caller can clear error status if needed
|
||||
if (onRequestSuccess) {
|
||||
await onRequestSuccess();
|
||||
}
|
||||
|
||||
// Log usage for non-streaming responses
|
||||
const usage = extractUsageFromResponse(responseBody, provider);
|
||||
appendRequestLog({ model, provider, connectionId, tokens: usage, status: "200 OK" }).catch(
|
||||
() => {}
|
||||
);
|
||||
|
||||
// Save structured call log with full payloads
|
||||
saveCallLog({
|
||||
method: "POST",
|
||||
path: clientRawRequest?.endpoint || "/v1/chat/completions",
|
||||
status: 200,
|
||||
model,
|
||||
provider,
|
||||
connectionId,
|
||||
duration: Date.now() - startTime,
|
||||
tokens: usage,
|
||||
requestBody: body,
|
||||
responseBody,
|
||||
sourceFormat,
|
||||
targetFormat,
|
||||
comboName,
|
||||
apiKeyId: apiKeyInfo?.id || null,
|
||||
apiKeyName: apiKeyInfo?.name || null,
|
||||
}).catch(() => {});
|
||||
if (usage && typeof usage === "object") {
|
||||
const msg = `[${new Date().toLocaleTimeString("en-US", { hour12: false, hour: "2-digit", minute: "2-digit" })}] 📊 [USAGE] ${provider.toUpperCase()} | in=${usage?.prompt_tokens || 0} | out=${usage?.completion_tokens || 0}${connectionId ? ` | account=${connectionId.slice(0, 8)}...` : ""}`;
|
||||
console.log(`${COLORS.green}${msg}${COLORS.reset}`);
|
||||
|
||||
saveRequestUsage({
|
||||
provider: provider || "unknown",
|
||||
model: model || "unknown",
|
||||
tokens: usage,
|
||||
timestamp: new Date().toISOString(),
|
||||
connectionId: connectionId || undefined,
|
||||
apiKeyId: apiKeyInfo?.id || undefined,
|
||||
apiKeyName: apiKeyInfo?.name || undefined,
|
||||
}).catch((err) => {
|
||||
console.error("Failed to save usage stats:", err.message);
|
||||
});
|
||||
}
|
||||
|
||||
// Translate response to client's expected format (usually OpenAI)
|
||||
const translatedResponse = needsTranslation(targetFormat, sourceFormat)
|
||||
? translateNonStreamingResponse(responseBody, targetFormat, sourceFormat)
|
||||
: responseBody;
|
||||
|
||||
// Add buffer and filter usage for client (to prevent CLI context errors)
|
||||
if (translatedResponse?.usage) {
|
||||
const buffered = addBufferToUsage(translatedResponse.usage);
|
||||
translatedResponse.usage = filterUsageForFormat(buffered, sourceFormat);
|
||||
} else {
|
||||
// Fallback: estimate usage when provider didn't return any
|
||||
const contentLength = JSON.stringify(
|
||||
translatedResponse?.choices?.[0]?.message?.content || ""
|
||||
).length;
|
||||
if (contentLength > 0) {
|
||||
const estimated = estimateUsage(body, contentLength, sourceFormat);
|
||||
translatedResponse.usage = filterUsageForFormat(estimated, sourceFormat);
|
||||
}
|
||||
}
|
||||
|
||||
// ── Phase 9.1: Cache store (non-streaming, temp=0) ──
|
||||
if (isCacheable(body, clientRawRequest?.headers)) {
|
||||
const signature = generateSignature(model, body.messages, body.temperature, body.top_p);
|
||||
const tokensSaved = usage?.prompt_tokens + usage?.completion_tokens || 0;
|
||||
setCachedResponse(signature, model, translatedResponse, tokensSaved);
|
||||
log?.debug?.("CACHE", `Stored response for ${model} (${tokensSaved} tokens)`);
|
||||
}
|
||||
|
||||
// ── Phase 9.2: Save for idempotency ──
|
||||
saveIdempotency(idempotencyKey, translatedResponse, 200);
|
||||
|
||||
return {
|
||||
success: true,
|
||||
response: new Response(JSON.stringify(translatedResponse), {
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
"Access-Control-Allow-Origin": "*",
|
||||
"X-OmniRoute-Cache": "MISS",
|
||||
},
|
||||
}),
|
||||
};
|
||||
}
|
||||
|
||||
// Streaming response
|
||||
|
||||
// Notify success - caller can clear error status if needed
|
||||
if (onRequestSuccess) {
|
||||
await onRequestSuccess();
|
||||
}
|
||||
|
||||
const responseHeaders = {
|
||||
"Content-Type": "text/event-stream",
|
||||
"Cache-Control": "no-cache",
|
||||
Connection: "keep-alive",
|
||||
"Access-Control-Allow-Origin": "*",
|
||||
};
|
||||
|
||||
// Create transform stream with logger for streaming response
|
||||
let transformStream;
|
||||
|
||||
// Callback to save call log when stream completes (streaming calls were never logged before!)
|
||||
const onStreamComplete = ({ status: streamStatus, usage: streamUsage }) => {
|
||||
saveCallLog({
|
||||
method: "POST",
|
||||
path: clientRawRequest?.endpoint || "/v1/chat/completions",
|
||||
status: streamStatus || 200,
|
||||
model,
|
||||
provider,
|
||||
connectionId,
|
||||
duration: Date.now() - startTime,
|
||||
tokens: streamUsage || {},
|
||||
requestBody: body,
|
||||
sourceFormat,
|
||||
targetFormat,
|
||||
comboName,
|
||||
apiKeyId: apiKeyInfo?.id || null,
|
||||
apiKeyName: apiKeyInfo?.name || null,
|
||||
}).catch(() => {});
|
||||
};
|
||||
|
||||
// For Codex provider, translate response from openai-responses to openai (Chat Completions) format
|
||||
// UNLESS client is Droid CLI which expects openai-responses format back
|
||||
const isDroidCLI =
|
||||
userAgent?.toLowerCase().includes("droid") || userAgent?.toLowerCase().includes("codex-cli");
|
||||
const needsCodexTranslation =
|
||||
provider === "codex" &&
|
||||
targetFormat === FORMATS.OPENAI_RESPONSES &&
|
||||
sourceFormat === FORMATS.OPENAI &&
|
||||
!isResponsesEndpoint &&
|
||||
!isDroidCLI;
|
||||
|
||||
if (needsCodexTranslation) {
|
||||
// Codex returns openai-responses, translate to openai (Chat Completions) that clients expect
|
||||
log?.debug?.("STREAM", `Codex translation mode: openai-responses → openai`);
|
||||
transformStream = createSSETransformStreamWithLogger(
|
||||
"openai-responses",
|
||||
"openai",
|
||||
provider,
|
||||
reqLogger,
|
||||
toolNameMap,
|
||||
model,
|
||||
connectionId,
|
||||
body,
|
||||
onStreamComplete,
|
||||
apiKeyInfo
|
||||
);
|
||||
} else if (needsTranslation(targetFormat, sourceFormat)) {
|
||||
// Standard translation for other providers
|
||||
log?.debug?.("STREAM", `Translation mode: ${targetFormat} → ${sourceFormat}`);
|
||||
transformStream = createSSETransformStreamWithLogger(
|
||||
targetFormat,
|
||||
sourceFormat,
|
||||
provider,
|
||||
reqLogger,
|
||||
toolNameMap,
|
||||
model,
|
||||
connectionId,
|
||||
body,
|
||||
onStreamComplete,
|
||||
apiKeyInfo
|
||||
);
|
||||
} else {
|
||||
log?.debug?.("STREAM", `Standard passthrough mode`);
|
||||
transformStream = createPassthroughStreamWithLogger(
|
||||
provider,
|
||||
reqLogger,
|
||||
model,
|
||||
connectionId,
|
||||
body,
|
||||
onStreamComplete,
|
||||
apiKeyInfo
|
||||
);
|
||||
}
|
||||
|
||||
// ── Phase 9.3: Progress tracking (opt-in) ──
|
||||
const progressEnabled = wantsProgress(clientRawRequest?.headers);
|
||||
let finalStream;
|
||||
if (progressEnabled) {
|
||||
const progressTransform = createProgressTransform({ signal: streamController.signal });
|
||||
// Chain: provider → transform → progress → client
|
||||
const transformedBody = pipeWithDisconnect(providerResponse, transformStream, streamController);
|
||||
finalStream = transformedBody.pipeThrough(progressTransform);
|
||||
responseHeaders["X-OmniRoute-Progress"] = "enabled";
|
||||
} else {
|
||||
finalStream = pipeWithDisconnect(providerResponse, transformStream, streamController);
|
||||
}
|
||||
|
||||
return {
|
||||
success: true,
|
||||
response: new Response(finalStream, {
|
||||
headers: responseHeaders,
|
||||
}),
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if token is expired or about to expire
|
||||
*/
|
||||
export function isTokenExpiringSoon(expiresAt, bufferMs = 5 * 60 * 1000) {
|
||||
if (!expiresAt) return false;
|
||||
const expiresAtMs = new Date(expiresAt).getTime();
|
||||
return expiresAtMs - Date.now() < bufferMs;
|
||||
}
|
||||
171
open-sse/handlers/embeddings.ts
Normal file
171
open-sse/handlers/embeddings.ts
Normal file
@@ -0,0 +1,171 @@
|
||||
/**
|
||||
* Embedding Handler
|
||||
*
|
||||
* Handles POST /v1/embeddings requests.
|
||||
* Proxies to upstream embedding providers using OpenAI-compatible format.
|
||||
*
|
||||
* Request format (OpenAI-compatible):
|
||||
* {
|
||||
* "model": "nebius/Qwen/Qwen3-Embedding-8B",
|
||||
* "input": "text" | ["text1", "text2"],
|
||||
* "dimensions": 4096, // optional
|
||||
* "encoding_format": "float" // optional
|
||||
* }
|
||||
*/
|
||||
|
||||
import { getEmbeddingProvider, parseEmbeddingModel } from "../config/embeddingRegistry.ts";
|
||||
import { saveCallLog } from "@/lib/usageDb";
|
||||
|
||||
/**
|
||||
* Handle embedding request
|
||||
* @param {object} options
|
||||
* @param {object} options.body - Request body
|
||||
* @param {object} options.credentials - Provider credentials { apiKey, accessToken }
|
||||
* @param {object} options.log - Logger
|
||||
*/
|
||||
export async function handleEmbedding({ body, credentials, log }) {
|
||||
const { provider, model } = parseEmbeddingModel(body.model);
|
||||
const startTime = Date.now();
|
||||
|
||||
// Summarized request body for call log (avoid storing large embedding input arrays)
|
||||
const logRequestBody = {
|
||||
model: body.model,
|
||||
input_count: Array.isArray(body.input) ? body.input.length : 1,
|
||||
dimensions: body.dimensions || undefined,
|
||||
};
|
||||
|
||||
if (!provider) {
|
||||
return {
|
||||
success: false,
|
||||
status: 400,
|
||||
error: `Invalid embedding model: ${body.model}. Use format: provider/model`,
|
||||
};
|
||||
}
|
||||
|
||||
const providerConfig = getEmbeddingProvider(provider);
|
||||
if (!providerConfig) {
|
||||
return {
|
||||
success: false,
|
||||
status: 400,
|
||||
error: `Unknown embedding provider: ${provider}`,
|
||||
};
|
||||
}
|
||||
|
||||
// Build upstream request
|
||||
const upstreamBody: Record<string, any> = {
|
||||
model: model,
|
||||
input: body.input,
|
||||
};
|
||||
|
||||
// Pass optional parameters
|
||||
if (body.dimensions !== undefined) upstreamBody.dimensions = body.dimensions;
|
||||
if (body.encoding_format !== undefined) upstreamBody.encoding_format = body.encoding_format;
|
||||
|
||||
// Build headers
|
||||
const headers = {
|
||||
"Content-Type": "application/json",
|
||||
};
|
||||
|
||||
const token = credentials.apiKey || credentials.accessToken;
|
||||
if (providerConfig.authHeader === "bearer") {
|
||||
headers["Authorization"] = `Bearer ${token}`;
|
||||
} else if (providerConfig.authHeader === "x-api-key") {
|
||||
headers["x-api-key"] = token;
|
||||
}
|
||||
|
||||
if (log) {
|
||||
log.info(
|
||||
"EMBED",
|
||||
`${provider}/${model} | input: ${Array.isArray(body.input) ? body.input.length + " items" : "1 item"}`
|
||||
);
|
||||
}
|
||||
|
||||
try {
|
||||
const response = await fetch(providerConfig.baseUrl, {
|
||||
method: "POST",
|
||||
headers,
|
||||
body: JSON.stringify(upstreamBody),
|
||||
});
|
||||
|
||||
if (!response.ok) {
|
||||
const errorText = await response.text();
|
||||
if (log) {
|
||||
log.error("EMBED", `${provider} error ${response.status}: ${errorText.slice(0, 200)}`);
|
||||
}
|
||||
|
||||
// Save error call log for Logger panel
|
||||
saveCallLog({
|
||||
method: "POST",
|
||||
path: "/v1/embeddings",
|
||||
status: response.status,
|
||||
model: `${provider}/${model}`,
|
||||
provider,
|
||||
duration: Date.now() - startTime,
|
||||
error: errorText.slice(0, 500),
|
||||
requestBody: logRequestBody,
|
||||
}).catch(() => {});
|
||||
|
||||
return {
|
||||
success: false,
|
||||
status: response.status,
|
||||
error: errorText,
|
||||
};
|
||||
}
|
||||
|
||||
const data = await response.json();
|
||||
|
||||
// Save success call log for Logger panel
|
||||
// Embeddings only have input tokens (prompt_tokens + total_tokens), no output/completion tokens
|
||||
saveCallLog({
|
||||
method: "POST",
|
||||
path: "/v1/embeddings",
|
||||
status: 200,
|
||||
model: `${provider}/${model}`,
|
||||
provider,
|
||||
duration: Date.now() - startTime,
|
||||
tokens: {
|
||||
prompt_tokens: data.usage?.prompt_tokens || data.usage?.total_tokens || 0,
|
||||
completion_tokens: 0,
|
||||
},
|
||||
requestBody: logRequestBody,
|
||||
responseBody: {
|
||||
usage: data.usage || null,
|
||||
object: "list",
|
||||
data_count: data.data?.length || 0,
|
||||
},
|
||||
}).catch(() => {});
|
||||
|
||||
// Normalize response to OpenAI format
|
||||
return {
|
||||
success: true,
|
||||
data: {
|
||||
object: "list",
|
||||
data: data.data || data,
|
||||
model: `${provider}/${model}`,
|
||||
usage: data.usage || { prompt_tokens: 0, total_tokens: 0 },
|
||||
},
|
||||
};
|
||||
} catch (err) {
|
||||
if (log) {
|
||||
log.error("EMBED", `${provider} fetch error: ${err.message}`);
|
||||
}
|
||||
|
||||
// Save exception call log for Logger panel
|
||||
saveCallLog({
|
||||
method: "POST",
|
||||
path: "/v1/embeddings",
|
||||
status: 502,
|
||||
model: `${provider}/${model}`,
|
||||
provider,
|
||||
duration: Date.now() - startTime,
|
||||
error: err.message,
|
||||
requestBody: logRequestBody,
|
||||
}).catch(() => {});
|
||||
|
||||
return {
|
||||
success: false,
|
||||
status: 502,
|
||||
error: `Embedding provider error: ${err.message}`,
|
||||
};
|
||||
}
|
||||
}
|
||||
562
open-sse/handlers/imageGeneration.ts
Normal file
562
open-sse/handlers/imageGeneration.ts
Normal file
@@ -0,0 +1,562 @@
|
||||
/**
|
||||
* Image Generation Handler
|
||||
*
|
||||
* Handles POST /v1/images/generations requests.
|
||||
* Proxies to upstream image generation providers using OpenAI-compatible format.
|
||||
*
|
||||
* Request format (OpenAI-compatible):
|
||||
* {
|
||||
* "model": "openai/dall-e-3",
|
||||
* "prompt": "a beautiful sunset over mountains",
|
||||
* "n": 1,
|
||||
* "size": "1024x1024",
|
||||
* "quality": "standard", // optional: "standard" | "hd"
|
||||
* "response_format": "url" // optional: "url" | "b64_json"
|
||||
* }
|
||||
*/
|
||||
|
||||
import { getImageProvider, parseImageModel } from "../config/imageRegistry.ts";
|
||||
import { saveCallLog } from "@/lib/usageDb";
|
||||
|
||||
/**
|
||||
* Handle image generation request
|
||||
* @param {object} options
|
||||
* @param {object} options.body - Request body
|
||||
* @param {object} options.credentials - Provider credentials { apiKey, accessToken }
|
||||
* @param {object} options.log - Logger
|
||||
*/
|
||||
export async function handleImageGeneration({ body, credentials, log }) {
|
||||
const { provider, model } = parseImageModel(body.model);
|
||||
|
||||
if (!provider) {
|
||||
return {
|
||||
success: false,
|
||||
status: 400,
|
||||
error: `Invalid image model: ${body.model}. Use format: provider/model`,
|
||||
};
|
||||
}
|
||||
|
||||
const providerConfig = getImageProvider(provider);
|
||||
if (!providerConfig) {
|
||||
return {
|
||||
success: false,
|
||||
status: 400,
|
||||
error: `Unknown image provider: ${provider}`,
|
||||
};
|
||||
}
|
||||
|
||||
// Route to format-specific handler
|
||||
if (providerConfig.format === "gemini-image") {
|
||||
return handleGeminiImageGeneration({ model, providerConfig, body, credentials, log });
|
||||
}
|
||||
|
||||
if (providerConfig.format === "hyperbolic") {
|
||||
return handleHyperbolicImageGeneration({
|
||||
model,
|
||||
provider,
|
||||
providerConfig,
|
||||
body,
|
||||
credentials,
|
||||
log,
|
||||
});
|
||||
}
|
||||
|
||||
if (providerConfig.format === "nanobanana") {
|
||||
return handleNanoBananaImageGeneration({
|
||||
model,
|
||||
provider,
|
||||
providerConfig,
|
||||
body,
|
||||
credentials,
|
||||
log,
|
||||
});
|
||||
}
|
||||
|
||||
return handleOpenAIImageGeneration({ model, provider, providerConfig, body, credentials, log });
|
||||
}
|
||||
|
||||
/**
|
||||
* Handle Gemini-format image generation (Antigravity / Nano Banana)
|
||||
* Uses Gemini's generateContent API with responseModalities: ["TEXT", "IMAGE"]
|
||||
*/
|
||||
async function handleGeminiImageGeneration({ model, providerConfig, body, credentials, log }) {
|
||||
const startTime = Date.now();
|
||||
const url = `${providerConfig.baseUrl}/${model}:generateContent`;
|
||||
const provider = "antigravity";
|
||||
|
||||
// Summarized request for call log
|
||||
const logRequestBody = {
|
||||
model: body.model,
|
||||
prompt:
|
||||
typeof body.prompt === "string"
|
||||
? body.prompt.slice(0, 200)
|
||||
: String(body.prompt ?? "").slice(0, 200),
|
||||
size: body.size || "default",
|
||||
n: body.n || 1,
|
||||
};
|
||||
|
||||
const geminiBody = {
|
||||
contents: [
|
||||
{
|
||||
parts: [{ text: body.prompt }],
|
||||
},
|
||||
],
|
||||
generationConfig: {
|
||||
responseModalities: ["TEXT", "IMAGE"],
|
||||
},
|
||||
};
|
||||
|
||||
const token = credentials.accessToken || credentials.apiKey;
|
||||
const headers = {
|
||||
"Content-Type": "application/json",
|
||||
Authorization: `Bearer ${token}`,
|
||||
};
|
||||
|
||||
if (log) {
|
||||
const promptPreview =
|
||||
typeof body.prompt === "string"
|
||||
? body.prompt.slice(0, 60)
|
||||
: String(body.prompt ?? "").slice(0, 60);
|
||||
log.info(
|
||||
"IMAGE",
|
||||
`antigravity/${model} (gemini) | prompt: "${promptPreview}..." | format: gemini-image`
|
||||
);
|
||||
}
|
||||
|
||||
try {
|
||||
const response = await fetch(url, {
|
||||
method: "POST",
|
||||
headers,
|
||||
body: JSON.stringify(geminiBody),
|
||||
});
|
||||
|
||||
if (!response.ok) {
|
||||
const errorText = await response.text();
|
||||
if (log) {
|
||||
log.error("IMAGE", `antigravity error ${response.status}: ${errorText.slice(0, 200)}`);
|
||||
}
|
||||
|
||||
saveCallLog({
|
||||
method: "POST",
|
||||
path: "/v1/images/generations",
|
||||
status: response.status,
|
||||
model: `antigravity/${model}`,
|
||||
provider,
|
||||
duration: Date.now() - startTime,
|
||||
error: errorText.slice(0, 500),
|
||||
requestBody: logRequestBody,
|
||||
}).catch(() => {});
|
||||
|
||||
return { success: false, status: response.status, error: errorText };
|
||||
}
|
||||
|
||||
const data = await response.json();
|
||||
|
||||
// Extract image data from Gemini response
|
||||
const images = [];
|
||||
const candidates = data.candidates || [];
|
||||
for (const candidate of candidates) {
|
||||
const parts = candidate.content?.parts || [];
|
||||
for (const part of parts) {
|
||||
if (part.inlineData) {
|
||||
images.push({
|
||||
b64_json: part.inlineData.data,
|
||||
revised_prompt: parts.find((p) => p.text)?.text || body.prompt,
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
saveCallLog({
|
||||
method: "POST",
|
||||
path: "/v1/images/generations",
|
||||
status: 200,
|
||||
model: `antigravity/${model}`,
|
||||
provider,
|
||||
duration: Date.now() - startTime,
|
||||
tokens: { prompt_tokens: 0, completion_tokens: 0 },
|
||||
requestBody: logRequestBody,
|
||||
responseBody: { images_count: images.length },
|
||||
}).catch(() => {});
|
||||
|
||||
return {
|
||||
success: true,
|
||||
data: {
|
||||
created: Math.floor(Date.now() / 1000),
|
||||
data: images,
|
||||
},
|
||||
};
|
||||
} catch (err) {
|
||||
if (log) {
|
||||
log.error("IMAGE", `antigravity fetch error: ${err.message}`);
|
||||
}
|
||||
|
||||
saveCallLog({
|
||||
method: "POST",
|
||||
path: "/v1/images/generations",
|
||||
status: 502,
|
||||
model: `antigravity/${model}`,
|
||||
provider,
|
||||
duration: Date.now() - startTime,
|
||||
error: err.message,
|
||||
requestBody: logRequestBody,
|
||||
}).catch(() => {});
|
||||
|
||||
return { success: false, status: 502, error: `Image provider error: ${err.message}` };
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Handle OpenAI-compatible image generation (standard providers + Nebius fallback)
|
||||
*/
|
||||
async function handleOpenAIImageGeneration({
|
||||
model,
|
||||
provider,
|
||||
providerConfig,
|
||||
body,
|
||||
credentials,
|
||||
log,
|
||||
}) {
|
||||
const startTime = Date.now();
|
||||
|
||||
// Summarized request for call log
|
||||
const logRequestBody = {
|
||||
model: body.model,
|
||||
prompt:
|
||||
typeof body.prompt === "string"
|
||||
? body.prompt.slice(0, 200)
|
||||
: String(body.prompt ?? "").slice(0, 200),
|
||||
size: body.size || "default",
|
||||
n: body.n || 1,
|
||||
quality: body.quality || undefined,
|
||||
};
|
||||
|
||||
// Build upstream request (OpenAI-compatible format)
|
||||
const upstreamBody: Record<string, any> = {
|
||||
model: model,
|
||||
prompt: body.prompt,
|
||||
};
|
||||
|
||||
// Pass optional parameters
|
||||
if (body.n !== undefined) upstreamBody.n = body.n;
|
||||
if (body.size !== undefined) upstreamBody.size = body.size;
|
||||
if (body.quality !== undefined) upstreamBody.quality = body.quality;
|
||||
if (body.response_format !== undefined) upstreamBody.response_format = body.response_format;
|
||||
if (body.style !== undefined) upstreamBody.style = body.style;
|
||||
|
||||
// Build headers
|
||||
const headers = {
|
||||
"Content-Type": "application/json",
|
||||
};
|
||||
|
||||
const token = credentials.apiKey || credentials.accessToken;
|
||||
if (providerConfig.authHeader === "bearer") {
|
||||
headers["Authorization"] = `Bearer ${token}`;
|
||||
} else if (providerConfig.authHeader === "x-api-key") {
|
||||
headers["x-api-key"] = token;
|
||||
}
|
||||
|
||||
if (log) {
|
||||
const promptPreview =
|
||||
typeof body.prompt === "string"
|
||||
? body.prompt.slice(0, 60)
|
||||
: String(body.prompt ?? "").slice(0, 60);
|
||||
log.info(
|
||||
"IMAGE",
|
||||
`${provider}/${model} | prompt: "${promptPreview}..." | size: ${body.size || "default"}`
|
||||
);
|
||||
}
|
||||
|
||||
const requestBody = JSON.stringify(upstreamBody);
|
||||
|
||||
// Try primary URL
|
||||
let result = await fetchImageEndpoint(
|
||||
providerConfig.baseUrl,
|
||||
headers,
|
||||
requestBody,
|
||||
provider,
|
||||
log
|
||||
);
|
||||
|
||||
// Fallback for providers with fallbackUrl (e.g., Nebius)
|
||||
if (
|
||||
!result.success &&
|
||||
providerConfig.fallbackUrl &&
|
||||
[404, 410, 502, 503].includes(result.status)
|
||||
) {
|
||||
if (log) {
|
||||
log.info("IMAGE", `${provider}: primary URL failed (${result.status}), trying fallback...`);
|
||||
}
|
||||
result = await fetchImageEndpoint(
|
||||
providerConfig.fallbackUrl,
|
||||
headers,
|
||||
requestBody,
|
||||
provider,
|
||||
log
|
||||
);
|
||||
}
|
||||
|
||||
// Save call log after result is determined
|
||||
saveCallLog({
|
||||
method: "POST",
|
||||
path: "/v1/images/generations",
|
||||
status: result.status || (result.success ? 200 : 502),
|
||||
model: `${provider}/${model}`,
|
||||
provider,
|
||||
duration: Date.now() - startTime,
|
||||
tokens: { prompt_tokens: 0, completion_tokens: 0 },
|
||||
error: result.success
|
||||
? null
|
||||
: typeof result.error === "string"
|
||||
? result.error.slice(0, 500)
|
||||
: null,
|
||||
requestBody: logRequestBody,
|
||||
responseBody: result.success ? { images_count: result.data?.data?.length || 0 } : null,
|
||||
}).catch(() => {});
|
||||
|
||||
return result;
|
||||
}
|
||||
|
||||
/**
|
||||
* Fetch a single image endpoint and normalize response
|
||||
*/
|
||||
async function fetchImageEndpoint(url, headers, body, provider, log) {
|
||||
try {
|
||||
const response = await fetch(url, {
|
||||
method: "POST",
|
||||
headers,
|
||||
body,
|
||||
});
|
||||
|
||||
if (!response.ok) {
|
||||
const errorText = await response.text();
|
||||
if (log) {
|
||||
log.error("IMAGE", `${provider} error ${response.status}: ${errorText.slice(0, 200)}`);
|
||||
}
|
||||
return {
|
||||
success: false,
|
||||
status: response.status,
|
||||
error: errorText,
|
||||
};
|
||||
}
|
||||
|
||||
const data = await response.json();
|
||||
|
||||
// Normalize response to OpenAI format
|
||||
return {
|
||||
success: true,
|
||||
data: {
|
||||
created: data.created || Math.floor(Date.now() / 1000),
|
||||
data: data.data || [],
|
||||
},
|
||||
};
|
||||
} catch (err) {
|
||||
if (log) {
|
||||
log.error("IMAGE", `${provider} fetch error: ${err.message}`);
|
||||
}
|
||||
return {
|
||||
success: false,
|
||||
status: 502,
|
||||
error: `Image provider error: ${err.message}`,
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Handle Hyperbolic image generation
|
||||
* Uses { model_name, prompt, height, width } and returns { images: [{ image: base64 }] }
|
||||
*/
|
||||
async function handleHyperbolicImageGeneration({
|
||||
model,
|
||||
provider,
|
||||
providerConfig,
|
||||
body,
|
||||
credentials,
|
||||
log,
|
||||
}) {
|
||||
const startTime = Date.now();
|
||||
const token = credentials.apiKey || credentials.accessToken;
|
||||
|
||||
const [width, height] = (body.size || "1024x1024").split("x").map(Number);
|
||||
|
||||
const upstreamBody = {
|
||||
model_name: model,
|
||||
prompt: body.prompt,
|
||||
height: height || 1024,
|
||||
width: width || 1024,
|
||||
backend: "auto",
|
||||
};
|
||||
|
||||
if (log) {
|
||||
const promptPreview = String(body.prompt ?? "").slice(0, 60);
|
||||
log.info("IMAGE", `${provider}/${model} (hyperbolic) | prompt: "${promptPreview}..."`);
|
||||
}
|
||||
|
||||
try {
|
||||
const response = await fetch(providerConfig.baseUrl, {
|
||||
method: "POST",
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
Authorization: `Bearer ${token}`,
|
||||
},
|
||||
body: JSON.stringify(upstreamBody),
|
||||
});
|
||||
|
||||
if (!response.ok) {
|
||||
const errorText = await response.text();
|
||||
if (log)
|
||||
log.error("IMAGE", `${provider} error ${response.status}: ${errorText.slice(0, 200)}`);
|
||||
|
||||
saveCallLog({
|
||||
method: "POST",
|
||||
path: "/v1/images/generations",
|
||||
status: response.status,
|
||||
model: `${provider}/${model}`,
|
||||
provider,
|
||||
duration: Date.now() - startTime,
|
||||
error: errorText.slice(0, 500),
|
||||
}).catch(() => {});
|
||||
|
||||
return { success: false, status: response.status, error: errorText };
|
||||
}
|
||||
|
||||
const data = await response.json();
|
||||
// Transform { images: [{ image: base64 }] } → OpenAI format
|
||||
const images = (data.images || []).map((img) => ({
|
||||
b64_json: img.image,
|
||||
revised_prompt: body.prompt,
|
||||
}));
|
||||
|
||||
saveCallLog({
|
||||
method: "POST",
|
||||
path: "/v1/images/generations",
|
||||
status: 200,
|
||||
model: `${provider}/${model}`,
|
||||
provider,
|
||||
duration: Date.now() - startTime,
|
||||
responseBody: { images_count: images.length },
|
||||
}).catch(() => {});
|
||||
|
||||
return {
|
||||
success: true,
|
||||
data: { created: Math.floor(Date.now() / 1000), data: images },
|
||||
};
|
||||
} catch (err) {
|
||||
if (log) log.error("IMAGE", `${provider} fetch error: ${err.message}`);
|
||||
saveCallLog({
|
||||
method: "POST",
|
||||
path: "/v1/images/generations",
|
||||
status: 502,
|
||||
model: `${provider}/${model}`,
|
||||
provider,
|
||||
duration: Date.now() - startTime,
|
||||
error: err.message,
|
||||
}).catch(() => {});
|
||||
return { success: false, status: 502, error: `Image provider error: ${err.message}` };
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Handle NanoBanana image generation
|
||||
* Uses flash vs pro routing based on model ID
|
||||
*/
|
||||
async function handleNanoBananaImageGeneration({
|
||||
model,
|
||||
provider,
|
||||
providerConfig,
|
||||
body,
|
||||
credentials,
|
||||
log,
|
||||
}) {
|
||||
const startTime = Date.now();
|
||||
const token = credentials.apiKey || credentials.accessToken;
|
||||
|
||||
// Route to pro URL for "nanobanana-pro" model
|
||||
const isPro = model === "nanobanana-pro";
|
||||
const url = isPro && providerConfig.proUrl ? providerConfig.proUrl : providerConfig.baseUrl;
|
||||
|
||||
const upstreamBody = {
|
||||
prompt: body.prompt,
|
||||
};
|
||||
|
||||
if (log) {
|
||||
const promptPreview = String(body.prompt ?? "").slice(0, 60);
|
||||
log.info(
|
||||
"IMAGE",
|
||||
`${provider}/${model} (nanobanana ${isPro ? "pro" : "flash"}) | prompt: "${promptPreview}..."`
|
||||
);
|
||||
}
|
||||
|
||||
try {
|
||||
const response = await fetch(url, {
|
||||
method: "POST",
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
Authorization: `Bearer ${token}`,
|
||||
},
|
||||
body: JSON.stringify(upstreamBody),
|
||||
});
|
||||
|
||||
if (!response.ok) {
|
||||
const errorText = await response.text();
|
||||
if (log)
|
||||
log.error("IMAGE", `${provider} error ${response.status}: ${errorText.slice(0, 200)}`);
|
||||
|
||||
saveCallLog({
|
||||
method: "POST",
|
||||
path: "/v1/images/generations",
|
||||
status: response.status,
|
||||
model: `${provider}/${model}`,
|
||||
provider,
|
||||
duration: Date.now() - startTime,
|
||||
error: errorText.slice(0, 500),
|
||||
}).catch(() => {});
|
||||
|
||||
return { success: false, status: response.status, error: errorText };
|
||||
}
|
||||
|
||||
const data = await response.json();
|
||||
// Normalize NanoBanana response to OpenAI format
|
||||
const images = [];
|
||||
if (data.image) {
|
||||
images.push({ b64_json: data.image, revised_prompt: body.prompt });
|
||||
} else if (data.images) {
|
||||
for (const img of data.images) {
|
||||
images.push({
|
||||
b64_json: typeof img === "string" ? img : img.image || img.data,
|
||||
revised_prompt: body.prompt,
|
||||
});
|
||||
}
|
||||
} else if (data.data) {
|
||||
// Already OpenAI-like
|
||||
return { success: true, data };
|
||||
}
|
||||
|
||||
saveCallLog({
|
||||
method: "POST",
|
||||
path: "/v1/images/generations",
|
||||
status: 200,
|
||||
model: `${provider}/${model}`,
|
||||
provider,
|
||||
duration: Date.now() - startTime,
|
||||
responseBody: { images_count: images.length },
|
||||
}).catch(() => {});
|
||||
|
||||
return {
|
||||
success: true,
|
||||
data: { created: Math.floor(Date.now() / 1000), data: images },
|
||||
};
|
||||
} catch (err) {
|
||||
if (log) log.error("IMAGE", `${provider} fetch error: ${err.message}`);
|
||||
saveCallLog({
|
||||
method: "POST",
|
||||
path: "/v1/images/generations",
|
||||
status: 502,
|
||||
model: `${provider}/${model}`,
|
||||
provider,
|
||||
duration: Date.now() - startTime,
|
||||
error: err.message,
|
||||
}).catch(() => {});
|
||||
return { success: false, status: 502, error: `Image provider error: ${err.message}` };
|
||||
}
|
||||
}
|
||||
69
open-sse/handlers/moderations.ts
Normal file
69
open-sse/handlers/moderations.ts
Normal file
@@ -0,0 +1,69 @@
|
||||
/**
|
||||
* Moderation Handler
|
||||
*
|
||||
* Handles POST /v1/moderations (OpenAI Moderations API format).
|
||||
*/
|
||||
|
||||
import { getModerationProvider, parseModerationModel } from "../config/moderationRegistry.ts";
|
||||
import { errorResponse } from "../utils/error.ts";
|
||||
|
||||
/**
|
||||
* Handle moderation request
|
||||
*
|
||||
* @param {Object} options
|
||||
* @param {Object} options.body - JSON body { model, input }
|
||||
* @param {Object} options.credentials - Provider credentials { apiKey }
|
||||
* @returns {Response}
|
||||
*/
|
||||
/** @returns {Promise<any>} */
|
||||
export async function handleModeration({ body, credentials }) {
|
||||
if (!body.input) {
|
||||
return errorResponse(400, "input is required");
|
||||
}
|
||||
|
||||
// Default to latest moderation model
|
||||
const model = body.model || "omni-moderation-latest";
|
||||
const { provider: providerId, model: modelId } = parseModerationModel(model);
|
||||
const providerConfig = providerId ? getModerationProvider(providerId) : null;
|
||||
|
||||
if (!providerConfig) {
|
||||
return errorResponse(
|
||||
400,
|
||||
`No moderation provider found for model "${model}". Available: openai`
|
||||
);
|
||||
}
|
||||
|
||||
const token = credentials?.apiKey || credentials?.accessToken;
|
||||
if (!token) {
|
||||
return errorResponse(401, `No credentials for moderation provider: ${providerId}`);
|
||||
}
|
||||
|
||||
try {
|
||||
const res = await fetch(providerConfig.baseUrl, {
|
||||
method: "POST",
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
Authorization: `Bearer ${token}`,
|
||||
},
|
||||
body: JSON.stringify({
|
||||
model: modelId,
|
||||
input: body.input,
|
||||
}),
|
||||
});
|
||||
|
||||
if (!res.ok) {
|
||||
const errText = await res.text();
|
||||
return new Response(errText, {
|
||||
status: res.status,
|
||||
headers: { "Content-Type": "application/json", "Access-Control-Allow-Origin": "*" },
|
||||
});
|
||||
}
|
||||
|
||||
const data = await res.json();
|
||||
return Response.json(data, {
|
||||
headers: { "Access-Control-Allow-Origin": "*" },
|
||||
});
|
||||
} catch (err) {
|
||||
return errorResponse(500, `Moderation request failed: ${err.message}`);
|
||||
}
|
||||
}
|
||||
137
open-sse/handlers/rerank.ts
Normal file
137
open-sse/handlers/rerank.ts
Normal file
@@ -0,0 +1,137 @@
|
||||
/**
|
||||
* Rerank Handler
|
||||
*
|
||||
* Handles /v1/rerank requests following the Cohere rerank API format.
|
||||
* Routes to the appropriate provider based on the model prefix or lookup.
|
||||
*/
|
||||
|
||||
import { getRerankProvider, parseRerankModel } from "../config/rerankRegistry.ts";
|
||||
import { errorResponse } from "../utils/error.ts";
|
||||
|
||||
/**
|
||||
* Build authorization header for a rerank provider
|
||||
*/
|
||||
function buildAuthHeader(providerConfig, token) {
|
||||
if (providerConfig.authHeader === "bearer") {
|
||||
return { Authorization: `Bearer ${token}` };
|
||||
}
|
||||
return {};
|
||||
}
|
||||
|
||||
/**
|
||||
* Transform request body for provider-specific formats (e.g. NVIDIA ranking API)
|
||||
*/
|
||||
function transformRequestForProvider(providerConfig, body) {
|
||||
if (providerConfig.format === "nvidia") {
|
||||
return {
|
||||
model: body.model,
|
||||
query: { text: body.query },
|
||||
passages: (body.documents || []).map((doc) => ({
|
||||
text: typeof doc === "string" ? doc : doc.text || "",
|
||||
})),
|
||||
top_n: body.top_n,
|
||||
};
|
||||
}
|
||||
// Default: Cohere-compatible format (used by Together, Fireworks, Cohere)
|
||||
return body;
|
||||
}
|
||||
|
||||
/**
|
||||
* Transform response from provider-specific formats back to Cohere format
|
||||
*/
|
||||
function transformResponseFromProvider(providerConfig, data) {
|
||||
if (providerConfig.format === "nvidia") {
|
||||
return {
|
||||
id: data.id || `rerank-${Date.now()}`,
|
||||
results: (data.rankings || []).map((r) => ({
|
||||
index: r.index,
|
||||
relevance_score: r.logit || r.score || 0,
|
||||
document: { text: r.text || "" },
|
||||
})),
|
||||
meta: {
|
||||
api_version: { version: "2" },
|
||||
billed_units: { search_units: 1 },
|
||||
},
|
||||
};
|
||||
}
|
||||
return data;
|
||||
}
|
||||
|
||||
/**
|
||||
* Handle a rerank request
|
||||
*
|
||||
* @param {Object} options
|
||||
* @param {string} options.model - Model ID (e.g. "rerank-v3.5" or "cohere/rerank-v3.5")
|
||||
* @param {string} options.query - Query to rank documents against
|
||||
* @param {string[]|Object[]} options.documents - Documents to rerank
|
||||
* @param {number} [options.top_n] - Number of top results to return
|
||||
* @param {boolean} [options.return_documents] - Whether to include document text in results
|
||||
* @param {Object} options.credentials - Provider credentials { apiKey, accessToken }
|
||||
* @returns {Response}
|
||||
*/
|
||||
/** @returns {Promise<any>} */
|
||||
export async function handleRerank({
|
||||
model,
|
||||
query,
|
||||
documents,
|
||||
top_n,
|
||||
return_documents,
|
||||
credentials,
|
||||
}) {
|
||||
if (!model) return errorResponse(400, "model is required");
|
||||
if (!query) return errorResponse(400, "query is required");
|
||||
if (!documents || !Array.isArray(documents) || documents.length === 0) {
|
||||
return errorResponse(400, "documents must be a non-empty array");
|
||||
}
|
||||
|
||||
const { provider: providerId, model: modelId } = parseRerankModel(model);
|
||||
const providerConfig = providerId ? getRerankProvider(providerId) : null;
|
||||
|
||||
if (!providerConfig) {
|
||||
return errorResponse(
|
||||
400,
|
||||
`No rerank provider found for model "${model}". Available: cohere, together, nvidia, fireworks`
|
||||
);
|
||||
}
|
||||
|
||||
const token = credentials?.apiKey || credentials?.accessToken;
|
||||
if (!token) {
|
||||
return errorResponse(401, `No credentials for rerank provider: ${providerId}`);
|
||||
}
|
||||
|
||||
const requestBody = transformRequestForProvider(providerConfig, {
|
||||
model: modelId,
|
||||
query,
|
||||
documents,
|
||||
top_n: top_n || documents.length,
|
||||
return_documents: return_documents !== false,
|
||||
});
|
||||
|
||||
try {
|
||||
const res = await fetch(providerConfig.baseUrl, {
|
||||
method: "POST",
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
...buildAuthHeader(providerConfig, token),
|
||||
},
|
||||
body: JSON.stringify(requestBody),
|
||||
});
|
||||
|
||||
if (!res.ok) {
|
||||
const errData = await res.json().catch(() => ({}));
|
||||
return errorResponse(
|
||||
res.status,
|
||||
errData.message || errData.error?.message || `Provider returned HTTP ${res.status}`
|
||||
);
|
||||
}
|
||||
|
||||
const data = await res.json();
|
||||
const result = transformResponseFromProvider(providerConfig, data);
|
||||
|
||||
return Response.json(result, {
|
||||
headers: { "Access-Control-Allow-Origin": "*" },
|
||||
});
|
||||
} catch (err) {
|
||||
return errorResponse(500, `Rerank request failed: ${err.message}`);
|
||||
}
|
||||
}
|
||||
290
open-sse/handlers/responseTranslator.ts
Normal file
290
open-sse/handlers/responseTranslator.ts
Normal file
@@ -0,0 +1,290 @@
|
||||
import { FORMATS } from "../translator/formats.ts";
|
||||
|
||||
/**
|
||||
* Translate non-streaming response to OpenAI format
|
||||
* Handles different provider response formats (Gemini, Claude, etc.)
|
||||
*/
|
||||
export function translateNonStreamingResponse(responseBody, targetFormat, sourceFormat) {
|
||||
// If already in source format (usually OpenAI), return as-is
|
||||
if (targetFormat === sourceFormat || targetFormat === FORMATS.OPENAI) {
|
||||
return responseBody;
|
||||
}
|
||||
|
||||
// Handle OpenAI Responses API format
|
||||
if (targetFormat === FORMATS.OPENAI_RESPONSES) {
|
||||
const response =
|
||||
responseBody?.object === "response" ? responseBody : responseBody?.response || responseBody;
|
||||
const output = Array.isArray(response?.output) ? response.output : [];
|
||||
const usage = response?.usage || responseBody?.usage;
|
||||
|
||||
let textContent = "";
|
||||
let reasoningContent = "";
|
||||
const toolCalls = [];
|
||||
|
||||
for (const item of output) {
|
||||
if (!item || typeof item !== "object") continue;
|
||||
|
||||
if (item.type === "message" && Array.isArray(item.content)) {
|
||||
for (const part of item.content) {
|
||||
if (!part || typeof part !== "object") continue;
|
||||
if (part.type === "output_text" && typeof part.text === "string") {
|
||||
textContent += part.text;
|
||||
} else if (part.type === "summary_text" && typeof part.text === "string") {
|
||||
reasoningContent += part.text;
|
||||
}
|
||||
}
|
||||
} else if (item.type === "reasoning" && Array.isArray(item.summary)) {
|
||||
for (const part of item.summary) {
|
||||
if (part?.type === "summary_text" && typeof part.text === "string") {
|
||||
reasoningContent += part.text;
|
||||
}
|
||||
}
|
||||
} else if (item.type === "function_call") {
|
||||
const callId = item.call_id || item.id || `call_${Date.now()}_${toolCalls.length}`;
|
||||
const fnArgs =
|
||||
typeof item.arguments === "string"
|
||||
? item.arguments
|
||||
: JSON.stringify(item.arguments || {});
|
||||
toolCalls.push({
|
||||
id: callId,
|
||||
type: "function",
|
||||
function: {
|
||||
name: item.name || "",
|
||||
arguments: fnArgs,
|
||||
},
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
const message: Record<string, any> = { role: "assistant" };
|
||||
if (textContent) {
|
||||
message.content = textContent;
|
||||
}
|
||||
if (reasoningContent) {
|
||||
message.reasoning_content = reasoningContent;
|
||||
}
|
||||
if (toolCalls.length > 0) {
|
||||
message.tool_calls = toolCalls;
|
||||
}
|
||||
if (!message.content && !message.tool_calls) {
|
||||
message.content = "";
|
||||
}
|
||||
|
||||
const createdAt = Number(response?.created_at) || Math.floor(Date.now() / 1000);
|
||||
const model = response?.model || responseBody?.model || "openai-responses";
|
||||
const finishReason = toolCalls.length > 0 ? "tool_calls" : "stop";
|
||||
|
||||
const result: Record<string, any> = {
|
||||
id: `chatcmpl-${response?.id || Date.now()}`,
|
||||
object: "chat.completion",
|
||||
created: createdAt,
|
||||
model,
|
||||
choices: [
|
||||
{
|
||||
index: 0,
|
||||
message,
|
||||
finish_reason: finishReason,
|
||||
},
|
||||
],
|
||||
};
|
||||
|
||||
if (usage && typeof usage === "object") {
|
||||
const inputTokens = usage.input_tokens || 0;
|
||||
const outputTokens = usage.output_tokens || 0;
|
||||
result.usage = {
|
||||
prompt_tokens: inputTokens,
|
||||
completion_tokens: outputTokens,
|
||||
total_tokens: inputTokens + outputTokens,
|
||||
};
|
||||
|
||||
if (usage.reasoning_tokens > 0) {
|
||||
result.usage.completion_tokens_details = {
|
||||
reasoning_tokens: usage.reasoning_tokens,
|
||||
};
|
||||
}
|
||||
if (usage.cache_read_input_tokens > 0 || usage.cache_creation_input_tokens > 0) {
|
||||
result.usage.prompt_tokens_details = {};
|
||||
if (usage.cache_read_input_tokens > 0) {
|
||||
result.usage.prompt_tokens_details.cached_tokens = usage.cache_read_input_tokens;
|
||||
}
|
||||
if (usage.cache_creation_input_tokens > 0) {
|
||||
result.usage.prompt_tokens_details.cache_creation_tokens =
|
||||
usage.cache_creation_input_tokens;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return result;
|
||||
}
|
||||
|
||||
// Handle Gemini/Antigravity format
|
||||
if (
|
||||
targetFormat === FORMATS.GEMINI ||
|
||||
targetFormat === FORMATS.ANTIGRAVITY ||
|
||||
targetFormat === FORMATS.GEMINI_CLI
|
||||
) {
|
||||
const response = responseBody.response || responseBody;
|
||||
if (!response?.candidates?.[0]) {
|
||||
return responseBody; // Can't translate, return raw
|
||||
}
|
||||
|
||||
const candidate = response.candidates[0];
|
||||
const content = candidate.content;
|
||||
const usage = response.usageMetadata || responseBody.usageMetadata;
|
||||
|
||||
// Build message content
|
||||
let textContent = "";
|
||||
const toolCalls = [];
|
||||
let reasoningContent = "";
|
||||
|
||||
if (content?.parts) {
|
||||
for (const part of content.parts) {
|
||||
// Handle thinking/reasoning
|
||||
if (part.thought === true && part.text) {
|
||||
reasoningContent += part.text;
|
||||
}
|
||||
// Regular text
|
||||
else if (part.text !== undefined) {
|
||||
textContent += part.text;
|
||||
}
|
||||
// Function calls
|
||||
if (part.functionCall) {
|
||||
toolCalls.push({
|
||||
id: `call_${part.functionCall.name}_${Date.now()}_${toolCalls.length}`,
|
||||
type: "function",
|
||||
function: {
|
||||
name: part.functionCall.name,
|
||||
arguments: JSON.stringify(part.functionCall.args || {}),
|
||||
},
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Build OpenAI format message
|
||||
const message: Record<string, any> = { role: "assistant" };
|
||||
if (textContent) {
|
||||
message.content = textContent;
|
||||
}
|
||||
if (reasoningContent) {
|
||||
message.reasoning_content = reasoningContent;
|
||||
}
|
||||
if (toolCalls.length > 0) {
|
||||
message.tool_calls = toolCalls;
|
||||
}
|
||||
// If no content at all, set content to empty string
|
||||
if (!message.content && !message.tool_calls) {
|
||||
message.content = "";
|
||||
}
|
||||
|
||||
// Determine finish reason
|
||||
let finishReason = (candidate.finishReason || "stop").toLowerCase();
|
||||
if (finishReason === "stop" && toolCalls.length > 0) {
|
||||
finishReason = "tool_calls";
|
||||
}
|
||||
|
||||
const result: Record<string, any> = {
|
||||
id: `chatcmpl-${response.responseId || Date.now()}`,
|
||||
object: "chat.completion",
|
||||
created: Math.floor(new Date(response.createTime || Date.now()).getTime() / 1000),
|
||||
model: response.modelVersion || "gemini",
|
||||
choices: [
|
||||
{
|
||||
index: 0,
|
||||
message,
|
||||
finish_reason: finishReason,
|
||||
},
|
||||
],
|
||||
};
|
||||
|
||||
// Add usage if available (match streaming translator: add thoughtsTokenCount to prompt_tokens)
|
||||
if (usage) {
|
||||
result.usage = {
|
||||
prompt_tokens: (usage.promptTokenCount || 0) + (usage.thoughtsTokenCount || 0),
|
||||
completion_tokens: usage.candidatesTokenCount || 0,
|
||||
total_tokens: usage.totalTokenCount || 0,
|
||||
};
|
||||
if (usage.thoughtsTokenCount > 0) {
|
||||
result.usage.completion_tokens_details = {
|
||||
reasoning_tokens: usage.thoughtsTokenCount,
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
return result;
|
||||
}
|
||||
|
||||
// Handle Claude format
|
||||
if (targetFormat === FORMATS.CLAUDE) {
|
||||
if (!responseBody.content) {
|
||||
return responseBody; // Can't translate, return raw
|
||||
}
|
||||
|
||||
let textContent = "";
|
||||
let thinkingContent = "";
|
||||
const toolCalls = [];
|
||||
|
||||
for (const block of responseBody.content) {
|
||||
if (block.type === "text") {
|
||||
textContent += block.text;
|
||||
} else if (block.type === "thinking") {
|
||||
thinkingContent += block.thinking || "";
|
||||
} else if (block.type === "tool_use") {
|
||||
toolCalls.push({
|
||||
id: block.id,
|
||||
type: "function",
|
||||
function: {
|
||||
name: block.name,
|
||||
arguments: JSON.stringify(block.input || {}),
|
||||
},
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
const message: Record<string, any> = { role: "assistant" };
|
||||
if (textContent) {
|
||||
message.content = textContent;
|
||||
}
|
||||
if (thinkingContent) {
|
||||
message.reasoning_content = thinkingContent;
|
||||
}
|
||||
if (toolCalls.length > 0) {
|
||||
message.tool_calls = toolCalls;
|
||||
}
|
||||
if (!message.content && !message.tool_calls) {
|
||||
message.content = "";
|
||||
}
|
||||
|
||||
let finishReason = responseBody.stop_reason || "stop";
|
||||
if (finishReason === "end_turn") finishReason = "stop";
|
||||
if (finishReason === "tool_use") finishReason = "tool_calls";
|
||||
|
||||
const result: Record<string, any> = {
|
||||
id: `chatcmpl-${responseBody.id || Date.now()}`,
|
||||
object: "chat.completion",
|
||||
created: Math.floor(Date.now() / 1000),
|
||||
model: responseBody.model || "claude",
|
||||
choices: [
|
||||
{
|
||||
index: 0,
|
||||
message,
|
||||
finish_reason: finishReason,
|
||||
},
|
||||
],
|
||||
};
|
||||
|
||||
if (responseBody.usage) {
|
||||
result.usage = {
|
||||
prompt_tokens: responseBody.usage.input_tokens || 0,
|
||||
completion_tokens: responseBody.usage.output_tokens || 0,
|
||||
total_tokens:
|
||||
(responseBody.usage.input_tokens || 0) + (responseBody.usage.output_tokens || 0),
|
||||
};
|
||||
}
|
||||
|
||||
return result;
|
||||
}
|
||||
|
||||
// Unknown format, return as-is
|
||||
return responseBody;
|
||||
}
|
||||
82
open-sse/handlers/responsesHandler.ts
Normal file
82
open-sse/handlers/responsesHandler.ts
Normal file
@@ -0,0 +1,82 @@
|
||||
/**
|
||||
* Responses API Handler for Workers
|
||||
* Converts Chat Completions to Codex Responses API format
|
||||
*/
|
||||
|
||||
import { handleChatCore } from "./chatCore.ts";
|
||||
import { convertResponsesApiFormat } from "../translator/helpers/responsesApiHelper.ts";
|
||||
import { createResponsesApiTransformStream } from "../transformer/responsesTransformer.ts";
|
||||
|
||||
/**
|
||||
* Handle /v1/responses request
|
||||
* @param {object} options
|
||||
* @param {object} options.body - Request body (Responses API format)
|
||||
* @param {object} options.modelInfo - { provider, model }
|
||||
* @param {object} options.credentials - Provider credentials
|
||||
* @param {object} options.log - Logger instance (optional)
|
||||
* @param {function} options.onCredentialsRefreshed - Callback when credentials are refreshed
|
||||
* @param {function} options.onRequestSuccess - Callback when request succeeds
|
||||
* @param {function} options.onDisconnect - Callback when client disconnects
|
||||
* @param {string} options.connectionId - Connection ID for usage tracking
|
||||
* @returns {Promise<{success: boolean, response?: Response, status?: number, error?: string}>}
|
||||
*/
|
||||
export async function handleResponsesCore({
|
||||
body,
|
||||
modelInfo,
|
||||
credentials,
|
||||
log,
|
||||
onCredentialsRefreshed,
|
||||
onRequestSuccess,
|
||||
onDisconnect,
|
||||
connectionId,
|
||||
}) {
|
||||
// Convert Responses API format to Chat Completions format
|
||||
const convertedBody = convertResponsesApiFormat(body);
|
||||
|
||||
// Ensure stream is enabled
|
||||
convertedBody.stream = true;
|
||||
|
||||
// Call chat core handler
|
||||
const result = await handleChatCore({
|
||||
body: convertedBody,
|
||||
modelInfo,
|
||||
credentials,
|
||||
log,
|
||||
onCredentialsRefreshed,
|
||||
onRequestSuccess,
|
||||
onDisconnect,
|
||||
clientRawRequest: null,
|
||||
connectionId,
|
||||
userAgent: null,
|
||||
comboName: null,
|
||||
} as any);
|
||||
|
||||
if (!result.success || !result.response) {
|
||||
return result;
|
||||
}
|
||||
|
||||
const response = result.response;
|
||||
const contentType = response.headers.get("Content-Type") || "";
|
||||
|
||||
// If not SSE or error, return as-is
|
||||
if (!contentType.includes("text/event-stream") || response.status !== 200) {
|
||||
return result;
|
||||
}
|
||||
|
||||
// Transform SSE stream to Responses API format (no logging in worker)
|
||||
const transformStream = createResponsesApiTransformStream(null);
|
||||
const transformedBody = response.body.pipeThrough(transformStream);
|
||||
|
||||
return {
|
||||
success: true,
|
||||
response: new Response(transformedBody, {
|
||||
status: 200,
|
||||
headers: {
|
||||
"Content-Type": "text/event-stream",
|
||||
"Cache-Control": "no-cache",
|
||||
Connection: "keep-alive",
|
||||
"Access-Control-Allow-Origin": "*",
|
||||
},
|
||||
}),
|
||||
};
|
||||
}
|
||||
124
open-sse/handlers/sseParser.ts
Normal file
124
open-sse/handlers/sseParser.ts
Normal file
@@ -0,0 +1,124 @@
|
||||
/**
|
||||
* Convert OpenAI-style SSE chunks into a single non-streaming JSON response.
|
||||
* Used as a fallback when upstream returns text/event-stream for stream=false.
|
||||
*/
|
||||
export function parseSSEToOpenAIResponse(rawSSE, fallbackModel) {
|
||||
const lines = String(rawSSE || "").split("\n");
|
||||
const chunks = [];
|
||||
|
||||
for (const line of lines) {
|
||||
const trimmed = line.trim();
|
||||
if (!trimmed.startsWith("data:")) continue;
|
||||
const payload = trimmed.slice(5).trim();
|
||||
if (!payload || payload === "[DONE]") continue;
|
||||
try {
|
||||
chunks.push(JSON.parse(payload));
|
||||
} catch {
|
||||
// Ignore malformed SSE lines and continue best-effort parsing.
|
||||
}
|
||||
}
|
||||
|
||||
if (chunks.length === 0) return null;
|
||||
|
||||
const first = chunks[0];
|
||||
const contentParts = [];
|
||||
const reasoningParts = [];
|
||||
let finishReason = "stop";
|
||||
let usage = null;
|
||||
|
||||
for (const chunk of chunks) {
|
||||
const choice = chunk?.choices?.[0];
|
||||
const delta = choice?.delta || {};
|
||||
|
||||
if (typeof delta.content === "string" && delta.content.length > 0) {
|
||||
contentParts.push(delta.content);
|
||||
}
|
||||
if (typeof delta.reasoning_content === "string" && delta.reasoning_content.length > 0) {
|
||||
reasoningParts.push(delta.reasoning_content);
|
||||
}
|
||||
if (choice?.finish_reason) {
|
||||
finishReason = choice.finish_reason;
|
||||
}
|
||||
if (chunk?.usage && typeof chunk.usage === "object") {
|
||||
usage = chunk.usage;
|
||||
}
|
||||
}
|
||||
|
||||
const message: Record<string, any> = { role: "assistant",
|
||||
content: contentParts.join(""),
|
||||
};
|
||||
if (reasoningParts.length > 0) {
|
||||
message.reasoning_content = reasoningParts.join("");
|
||||
}
|
||||
|
||||
const result: Record<string, any> = {
|
||||
id: first.id || `chatcmpl-${Date.now()}`,
|
||||
object: "chat.completion",
|
||||
created: first.created || Math.floor(Date.now() / 1000),
|
||||
model: first.model || fallbackModel || "unknown",
|
||||
choices: [
|
||||
{
|
||||
index: 0,
|
||||
message,
|
||||
finish_reason: finishReason,
|
||||
},
|
||||
],
|
||||
};
|
||||
|
||||
if (usage) {
|
||||
result.usage = usage;
|
||||
}
|
||||
|
||||
return result;
|
||||
}
|
||||
|
||||
/**
|
||||
* Convert Responses API SSE events into a single non-streaming response object.
|
||||
* Expects events such as response.created / response.in_progress / response.completed.
|
||||
*/
|
||||
export function parseSSEToResponsesOutput(rawSSE, fallbackModel) {
|
||||
const lines = String(rawSSE || "").split("\n");
|
||||
const events = [];
|
||||
|
||||
for (const line of lines) {
|
||||
const trimmed = line.trim();
|
||||
if (!trimmed.startsWith("data:")) continue;
|
||||
const payload = trimmed.slice(5).trim();
|
||||
if (!payload || payload === "[DONE]") continue;
|
||||
try {
|
||||
events.push(JSON.parse(payload));
|
||||
} catch {
|
||||
// Ignore malformed lines and continue best-effort parsing.
|
||||
}
|
||||
}
|
||||
|
||||
if (events.length === 0) return null;
|
||||
|
||||
let completed = null;
|
||||
let latestResponse = null;
|
||||
|
||||
for (const evt of events) {
|
||||
if (evt?.type === "response.completed" && evt.response) {
|
||||
completed = evt.response;
|
||||
}
|
||||
if (evt?.response && typeof evt.response === "object") {
|
||||
latestResponse = evt.response;
|
||||
} else if (evt?.object === "response") {
|
||||
latestResponse = evt;
|
||||
}
|
||||
}
|
||||
|
||||
const picked = completed || latestResponse;
|
||||
if (!picked || typeof picked !== "object") return null;
|
||||
|
||||
return {
|
||||
id: picked.id || `resp_${Date.now()}`,
|
||||
object: "response",
|
||||
model: picked.model || fallbackModel || "unknown",
|
||||
output: Array.isArray(picked.output) ? picked.output : [],
|
||||
usage: picked.usage || null,
|
||||
status: picked.status || (completed ? "completed" : "in_progress"),
|
||||
created_at: picked.created_at || Math.floor(Date.now() / 1000),
|
||||
metadata: picked.metadata || {},
|
||||
};
|
||||
}
|
||||
64
open-sse/handlers/usageExtractor.ts
Normal file
64
open-sse/handlers/usageExtractor.ts
Normal file
@@ -0,0 +1,64 @@
|
||||
/**
|
||||
* Extract usage from non-streaming response body
|
||||
* Handles different provider response formats
|
||||
*/
|
||||
export function extractUsageFromResponse(responseBody, provider) {
|
||||
if (!responseBody || typeof responseBody !== "object") return null;
|
||||
|
||||
// OpenAI format (has prompt_tokens / completion_tokens)
|
||||
if (
|
||||
responseBody.usage &&
|
||||
typeof responseBody.usage === "object" &&
|
||||
responseBody.usage.prompt_tokens !== undefined
|
||||
) {
|
||||
return {
|
||||
prompt_tokens: responseBody.usage.prompt_tokens || 0,
|
||||
completion_tokens: responseBody.usage.completion_tokens || 0,
|
||||
cached_tokens: responseBody.usage.prompt_tokens_details?.cached_tokens,
|
||||
reasoning_tokens: responseBody.usage.completion_tokens_details?.reasoning_tokens,
|
||||
};
|
||||
}
|
||||
|
||||
// OpenAI Responses API format (input_tokens / output_tokens)
|
||||
const responsesUsage = responseBody.response?.usage || responseBody.usage;
|
||||
if (
|
||||
responsesUsage &&
|
||||
typeof responsesUsage === "object" &&
|
||||
(responsesUsage.input_tokens !== undefined || responsesUsage.output_tokens !== undefined)
|
||||
) {
|
||||
return {
|
||||
prompt_tokens: responsesUsage.input_tokens || 0,
|
||||
completion_tokens: responsesUsage.output_tokens || 0,
|
||||
cached_tokens: responsesUsage.cache_read_input_tokens,
|
||||
cache_creation_input_tokens: responsesUsage.cache_creation_input_tokens,
|
||||
reasoning_tokens:
|
||||
responsesUsage.reasoning_tokens || responsesUsage.output_tokens_details?.reasoning_tokens,
|
||||
};
|
||||
}
|
||||
|
||||
// Claude format
|
||||
if (
|
||||
responseBody.usage &&
|
||||
typeof responseBody.usage === "object" &&
|
||||
(responseBody.usage.input_tokens !== undefined ||
|
||||
responseBody.usage.output_tokens !== undefined)
|
||||
) {
|
||||
return {
|
||||
prompt_tokens: responseBody.usage.input_tokens || 0,
|
||||
completion_tokens: responseBody.usage.output_tokens || 0,
|
||||
cache_read_input_tokens: responseBody.usage.cache_read_input_tokens,
|
||||
cache_creation_input_tokens: responseBody.usage.cache_creation_input_tokens,
|
||||
};
|
||||
}
|
||||
|
||||
// Gemini format
|
||||
if (responseBody.usageMetadata && typeof responseBody.usageMetadata === "object") {
|
||||
return {
|
||||
prompt_tokens: responseBody.usageMetadata.promptTokenCount || 0,
|
||||
completion_tokens: responseBody.usageMetadata.candidatesTokenCount || 0,
|
||||
reasoning_tokens: responseBody.usageMetadata.thoughtsTokenCount,
|
||||
};
|
||||
}
|
||||
|
||||
return null;
|
||||
}
|
||||
141
open-sse/index.ts
Normal file
141
open-sse/index.ts
Normal file
@@ -0,0 +1,141 @@
|
||||
// Patch global fetch with proxy support (must be first)
|
||||
import "./utils/proxyFetch.ts";
|
||||
|
||||
// Config
|
||||
export {
|
||||
PROVIDERS,
|
||||
OAUTH_ENDPOINTS,
|
||||
CACHE_TTL,
|
||||
DEFAULT_MAX_TOKENS,
|
||||
CLAUDE_SYSTEM_PROMPT,
|
||||
COOLDOWN_MS,
|
||||
BACKOFF_CONFIG,
|
||||
} from "./config/constants.ts";
|
||||
export {
|
||||
PROVIDER_MODELS,
|
||||
getProviderModels,
|
||||
getDefaultModel,
|
||||
isValidModel,
|
||||
findModelName,
|
||||
getModelTargetFormat,
|
||||
PROVIDER_ID_TO_ALIAS,
|
||||
getModelsByProviderId,
|
||||
} from "./config/providerModels.ts";
|
||||
|
||||
// Translator
|
||||
export { FORMATS } from "./translator/formats.ts";
|
||||
export {
|
||||
register,
|
||||
translateRequest,
|
||||
translateResponse,
|
||||
needsTranslation,
|
||||
initState,
|
||||
initTranslators,
|
||||
} from "./translator/index.ts";
|
||||
|
||||
// Services
|
||||
export {
|
||||
detectFormat,
|
||||
getProviderConfig,
|
||||
buildProviderUrl,
|
||||
buildProviderHeaders,
|
||||
getTargetFormat,
|
||||
} from "./services/provider.ts";
|
||||
|
||||
export { parseModel, resolveModelAliasFromMap, getModelInfoCore } from "./services/model.ts";
|
||||
|
||||
export {
|
||||
checkFallbackError,
|
||||
isAccountUnavailable,
|
||||
getUnavailableUntil,
|
||||
filterAvailableAccounts,
|
||||
} from "./services/accountFallback.ts";
|
||||
|
||||
export {
|
||||
TOKEN_EXPIRY_BUFFER_MS,
|
||||
refreshAccessToken,
|
||||
refreshClaudeOAuthToken,
|
||||
refreshGoogleToken,
|
||||
refreshQwenToken,
|
||||
refreshCodexToken,
|
||||
refreshIflowToken,
|
||||
refreshGitHubToken,
|
||||
refreshCopilotToken,
|
||||
getAccessToken,
|
||||
refreshTokenByProvider,
|
||||
} from "./services/tokenRefresh.ts";
|
||||
|
||||
// Handlers
|
||||
export { handleChatCore, isTokenExpiringSoon } from "./handlers/chatCore.ts";
|
||||
export {
|
||||
createStreamController,
|
||||
pipeWithDisconnect,
|
||||
createDisconnectAwareStream,
|
||||
} from "./utils/streamHandler.ts";
|
||||
|
||||
// Executors
|
||||
export { getExecutor, hasSpecializedExecutor } from "./executors/index.ts";
|
||||
|
||||
// Utils
|
||||
export { errorResponse, formatProviderError } from "./utils/error.ts";
|
||||
export {
|
||||
createSSETransformStreamWithLogger,
|
||||
createPassthroughStreamWithLogger,
|
||||
} from "./utils/stream.ts";
|
||||
|
||||
// Embeddings
|
||||
export { handleEmbedding } from "./handlers/embeddings.ts";
|
||||
export {
|
||||
EMBEDDING_PROVIDERS,
|
||||
getEmbeddingProvider,
|
||||
parseEmbeddingModel,
|
||||
getAllEmbeddingModels,
|
||||
} from "./config/embeddingRegistry.ts";
|
||||
|
||||
// Image Generation
|
||||
export { handleImageGeneration } from "./handlers/imageGeneration.ts";
|
||||
export {
|
||||
IMAGE_PROVIDERS,
|
||||
getImageProvider,
|
||||
parseImageModel,
|
||||
getAllImageModels,
|
||||
} from "./config/imageRegistry.ts";
|
||||
|
||||
// Think Tag Parser
|
||||
export {
|
||||
hasThinkTags,
|
||||
extractThinkTags,
|
||||
processStreamingThinkDelta,
|
||||
flushThinkBuffer,
|
||||
} from "./utils/thinkTagParser.ts";
|
||||
|
||||
// Rerank
|
||||
export { handleRerank } from "./handlers/rerank.ts";
|
||||
export {
|
||||
RERANK_PROVIDERS,
|
||||
getRerankProvider,
|
||||
parseRerankModel,
|
||||
getAllRerankModels,
|
||||
} from "./config/rerankRegistry.ts";
|
||||
|
||||
// Audio (Transcription + Speech)
|
||||
export { handleAudioTranscription } from "./handlers/audioTranscription.ts";
|
||||
export { handleAudioSpeech } from "./handlers/audioSpeech.ts";
|
||||
export {
|
||||
AUDIO_TRANSCRIPTION_PROVIDERS,
|
||||
AUDIO_SPEECH_PROVIDERS,
|
||||
getTranscriptionProvider,
|
||||
getSpeechProvider,
|
||||
parseTranscriptionModel,
|
||||
parseSpeechModel,
|
||||
getAllAudioModels,
|
||||
} from "./config/audioRegistry.ts";
|
||||
|
||||
// Moderations
|
||||
export { handleModeration } from "./handlers/moderations.ts";
|
||||
export {
|
||||
MODERATION_PROVIDERS,
|
||||
getModerationProvider,
|
||||
parseModerationModel,
|
||||
getAllModerationModels,
|
||||
} from "./config/moderationRegistry.ts";
|
||||
13
open-sse/package.json
Normal file
13
open-sse/package.json
Normal file
@@ -0,0 +1,13 @@
|
||||
{
|
||||
"name": "@omniroute/open-sse",
|
||||
"version": "0.0.1",
|
||||
"description": "Express SSE sidecar for OmniRoute — handles streaming, protocol translation, and provider orchestration",
|
||||
"type": "module",
|
||||
"main": "index.js",
|
||||
"types": "types.d.ts",
|
||||
"private": true,
|
||||
"exports": {
|
||||
".": "./index.js",
|
||||
"./*": "./*"
|
||||
}
|
||||
}
|
||||
514
open-sse/services/accountFallback.ts
Normal file
514
open-sse/services/accountFallback.ts
Normal file
@@ -0,0 +1,514 @@
|
||||
import {
|
||||
COOLDOWN_MS,
|
||||
BACKOFF_CONFIG,
|
||||
BACKOFF_STEPS_MS,
|
||||
RateLimitReason,
|
||||
HTTP_STATUS,
|
||||
PROVIDER_PROFILES,
|
||||
} from "../config/constants.ts";
|
||||
import { getProviderCategory } from "../config/providerRegistry.ts";
|
||||
|
||||
// ─── Provider Profile Helper ────────────────────────────────────────────────
|
||||
|
||||
/**
|
||||
* Get the resilience profile for a provider (oauth or apikey).
|
||||
* @param {string} provider - Provider ID or alias
|
||||
* @returns {import('../config/constants.js').PROVIDER_PROFILES['oauth']}
|
||||
*/
|
||||
export function getProviderProfile(provider) {
|
||||
const category = getProviderCategory(provider);
|
||||
return PROVIDER_PROFILES[category] ?? PROVIDER_PROFILES.apikey;
|
||||
}
|
||||
|
||||
// ─── Per-Model Lockout Tracking ─────────────────────────────────────────────
|
||||
// In-memory map: "provider:connectionId:model" → { reason, until, lockedAt }
|
||||
const modelLockouts = new Map();
|
||||
|
||||
// Auto-cleanup expired lockouts every 15 seconds
|
||||
const _cleanupTimer = setInterval(() => {
|
||||
const now = Date.now();
|
||||
for (const [key, entry] of modelLockouts) {
|
||||
if (now > entry.until) modelLockouts.delete(key);
|
||||
}
|
||||
}, 15_000);
|
||||
_cleanupTimer.unref(); // Don't prevent process exit
|
||||
|
||||
/**
|
||||
* Lock a specific model on a specific account
|
||||
* @param {string} provider
|
||||
* @param {string} connectionId
|
||||
* @param {string} model
|
||||
* @param {string} reason - from RateLimitReason
|
||||
* @param {number} cooldownMs
|
||||
*/
|
||||
export function lockModel(provider, connectionId, model, reason, cooldownMs) {
|
||||
if (!model) return; // No model → skip model-level locking
|
||||
const key = `${provider}:${connectionId}:${model}`;
|
||||
modelLockouts.set(key, {
|
||||
reason,
|
||||
until: Date.now() + cooldownMs,
|
||||
lockedAt: Date.now(),
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if a specific model on a specific account is locked
|
||||
* @returns {boolean}
|
||||
*/
|
||||
export function isModelLocked(provider, connectionId, model) {
|
||||
if (!model) return false;
|
||||
const key = `${provider}:${connectionId}:${model}`;
|
||||
const entry = modelLockouts.get(key);
|
||||
if (!entry) return false;
|
||||
if (Date.now() > entry.until) {
|
||||
modelLockouts.delete(key);
|
||||
return false;
|
||||
}
|
||||
return true;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get model lockout info (for debugging/dashboard)
|
||||
*/
|
||||
export function getModelLockoutInfo(provider, connectionId, model) {
|
||||
if (!model) return null;
|
||||
const key = `${provider}:${connectionId}:${model}`;
|
||||
const entry = modelLockouts.get(key);
|
||||
if (!entry || Date.now() > entry.until) return null;
|
||||
return {
|
||||
reason: entry.reason,
|
||||
remainingMs: entry.until - Date.now(),
|
||||
lockedAt: new Date(entry.lockedAt).toISOString(),
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Get all active model lockouts (for dashboard)
|
||||
*/
|
||||
export function getAllModelLockouts() {
|
||||
const now = Date.now();
|
||||
const active = [];
|
||||
for (const [key, entry] of modelLockouts) {
|
||||
if (now <= entry.until) {
|
||||
const [provider, connectionId, model] = key.split(":");
|
||||
active.push({
|
||||
provider,
|
||||
connectionId,
|
||||
model,
|
||||
reason: entry.reason,
|
||||
remainingMs: entry.until - now,
|
||||
});
|
||||
}
|
||||
}
|
||||
return active;
|
||||
}
|
||||
|
||||
// ─── Retry-After Parsing ────────────────────────────────────────────────────
|
||||
|
||||
/**
|
||||
* Parse retry-after information from JSON error response bodies.
|
||||
* Providers embed retry info in different formats.
|
||||
*
|
||||
* @param {string|object} responseBody - Raw response body or parsed JSON
|
||||
* @returns {{ retryAfterMs: number|null, reason: string }}
|
||||
*/
|
||||
export function parseRetryAfterFromBody(responseBody) {
|
||||
let body;
|
||||
try {
|
||||
body = typeof responseBody === "string" ? JSON.parse(responseBody) : responseBody;
|
||||
} catch {
|
||||
return { retryAfterMs: null, reason: RateLimitReason.UNKNOWN };
|
||||
}
|
||||
|
||||
if (!body) return { retryAfterMs: null, reason: RateLimitReason.UNKNOWN };
|
||||
|
||||
// Gemini: { error: { details: [{ retryDelay: "33s" }] } }
|
||||
const details = body.error?.details || body.details || [];
|
||||
for (const detail of Array.isArray(details) ? details : []) {
|
||||
if (detail.retryDelay) {
|
||||
return {
|
||||
retryAfterMs: parseDelayString(detail.retryDelay),
|
||||
reason: RateLimitReason.RATE_LIMIT_EXCEEDED,
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
// OpenAI: "Please retry after 20s" in message
|
||||
const msg = body.error?.message || body.message || "";
|
||||
const retryMatch = msg.match(/retry\s+after\s+(\d+)\s*s/i);
|
||||
if (retryMatch) {
|
||||
return {
|
||||
retryAfterMs: parseInt(retryMatch[1], 10) * 1000,
|
||||
reason: RateLimitReason.RATE_LIMIT_EXCEEDED,
|
||||
};
|
||||
}
|
||||
|
||||
// Anthropic: error type classification
|
||||
const errorType = body.error?.type || body.type || "";
|
||||
if (errorType === "rate_limit_error") {
|
||||
return { retryAfterMs: null, reason: RateLimitReason.RATE_LIMIT_EXCEEDED };
|
||||
}
|
||||
|
||||
// Classify by error message keywords
|
||||
const reason = classifyErrorText(msg || errorType);
|
||||
return { retryAfterMs: null, reason };
|
||||
}
|
||||
|
||||
/**
|
||||
* Parse delay strings like "33s", "2m", "1h", "1500ms"
|
||||
*/
|
||||
function parseDelayString(value) {
|
||||
if (!value) return null;
|
||||
const str = String(value).trim();
|
||||
const msMatch = str.match(/^(\d+)\s*ms$/i);
|
||||
if (msMatch) return parseInt(msMatch[1], 10);
|
||||
const secMatch = str.match(/^(\d+)\s*s$/i);
|
||||
if (secMatch) return parseInt(secMatch[1], 10) * 1000;
|
||||
const minMatch = str.match(/^(\d+)\s*m$/i);
|
||||
if (minMatch) return parseInt(minMatch[1], 10) * 60 * 1000;
|
||||
const hrMatch = str.match(/^(\d+)\s*h$/i);
|
||||
if (hrMatch) return parseInt(hrMatch[1], 10) * 3600 * 1000;
|
||||
// Bare number → seconds
|
||||
const num = parseInt(str, 10);
|
||||
return isNaN(num) ? null : num * 1000;
|
||||
}
|
||||
|
||||
// ─── Error Classification ───────────────────────────────────────────────────
|
||||
|
||||
/**
|
||||
* Classify error text into RateLimitReason
|
||||
*/
|
||||
export function classifyErrorText(errorText) {
|
||||
if (!errorText) return RateLimitReason.UNKNOWN;
|
||||
const lower = String(errorText).toLowerCase();
|
||||
|
||||
if (
|
||||
lower.includes("quota exceeded") ||
|
||||
lower.includes("quota depleted") ||
|
||||
lower.includes("billing")
|
||||
) {
|
||||
return RateLimitReason.QUOTA_EXHAUSTED;
|
||||
}
|
||||
if (
|
||||
lower.includes("rate limit") ||
|
||||
lower.includes("too many requests") ||
|
||||
lower.includes("rate_limit")
|
||||
) {
|
||||
return RateLimitReason.RATE_LIMIT_EXCEEDED;
|
||||
}
|
||||
if (
|
||||
lower.includes("capacity") ||
|
||||
lower.includes("overloaded") ||
|
||||
lower.includes("resource exhausted")
|
||||
) {
|
||||
return RateLimitReason.MODEL_CAPACITY;
|
||||
}
|
||||
if (
|
||||
lower.includes("unauthorized") ||
|
||||
lower.includes("invalid api key") ||
|
||||
lower.includes("authentication")
|
||||
) {
|
||||
return RateLimitReason.AUTH_ERROR;
|
||||
}
|
||||
if (lower.includes("server error") || lower.includes("internal error")) {
|
||||
return RateLimitReason.SERVER_ERROR;
|
||||
}
|
||||
return RateLimitReason.UNKNOWN;
|
||||
}
|
||||
|
||||
/**
|
||||
* Classify HTTP status + error text into RateLimitReason
|
||||
*/
|
||||
export function classifyError(status, errorText) {
|
||||
// Text classification takes priority (more specific)
|
||||
const textReason = classifyErrorText(errorText);
|
||||
if (textReason !== RateLimitReason.UNKNOWN) return textReason;
|
||||
|
||||
// Fall back to status code
|
||||
if (status === HTTP_STATUS.UNAUTHORIZED || status === HTTP_STATUS.FORBIDDEN) {
|
||||
return RateLimitReason.AUTH_ERROR;
|
||||
}
|
||||
if (status === HTTP_STATUS.PAYMENT_REQUIRED) {
|
||||
return RateLimitReason.QUOTA_EXHAUSTED;
|
||||
}
|
||||
if (status === HTTP_STATUS.RATE_LIMITED) {
|
||||
return RateLimitReason.RATE_LIMIT_EXCEEDED;
|
||||
}
|
||||
if (status === HTTP_STATUS.SERVICE_UNAVAILABLE || status === 529) {
|
||||
return RateLimitReason.MODEL_CAPACITY;
|
||||
}
|
||||
if (status >= 500) {
|
||||
return RateLimitReason.SERVER_ERROR;
|
||||
}
|
||||
return RateLimitReason.UNKNOWN;
|
||||
}
|
||||
|
||||
// ─── Configurable Backoff ───────────────────────────────────────────────────
|
||||
|
||||
/**
|
||||
* Get backoff duration from configurable steps.
|
||||
* @param {number} failureCount - Number of consecutive failures
|
||||
* @returns {number} Duration in ms
|
||||
*/
|
||||
export function getBackoffDuration(failureCount) {
|
||||
const idx = Math.min(failureCount, BACKOFF_STEPS_MS.length - 1);
|
||||
return BACKOFF_STEPS_MS[idx];
|
||||
}
|
||||
|
||||
// ─── Original API (Backward Compatible) ────────────────────────────────────
|
||||
|
||||
/**
|
||||
* Calculate exponential backoff cooldown for rate limits (429)
|
||||
* Level 0: 1s, Level 1: 2s, Level 2: 4s... → max 2 min
|
||||
* @param {number} backoffLevel - Current backoff level
|
||||
* @returns {number} Cooldown in milliseconds
|
||||
*/
|
||||
export function getQuotaCooldown(backoffLevel = 0) {
|
||||
const cooldown = BACKOFF_CONFIG.base * Math.pow(2, backoffLevel);
|
||||
return Math.min(cooldown, BACKOFF_CONFIG.max);
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if error should trigger account fallback (switch to next account)
|
||||
* @param {number} status - HTTP status code
|
||||
* @param {string} errorText - Error message text
|
||||
* @param {number} backoffLevel - Current backoff level for exponential backoff
|
||||
* @param {string} [model] - Optional model name for model-level lockout
|
||||
* @param {string} [provider] - Provider ID for profile-aware cooldowns
|
||||
* @returns {{ shouldFallback: boolean, cooldownMs: number, newBackoffLevel?: number, reason?: string }}
|
||||
*/
|
||||
export function checkFallbackError(
|
||||
status,
|
||||
errorText,
|
||||
backoffLevel = 0,
|
||||
model = null,
|
||||
provider = null
|
||||
) {
|
||||
// Check error message FIRST - specific patterns take priority over status codes
|
||||
if (errorText) {
|
||||
const errorStr = typeof errorText === "string" ? errorText : JSON.stringify(errorText);
|
||||
const lowerError = errorStr.toLowerCase();
|
||||
|
||||
if (lowerError.includes("no credentials")) {
|
||||
return {
|
||||
shouldFallback: true,
|
||||
cooldownMs: COOLDOWN_MS.notFound,
|
||||
reason: RateLimitReason.AUTH_ERROR,
|
||||
};
|
||||
}
|
||||
|
||||
if (lowerError.includes("request not allowed")) {
|
||||
return {
|
||||
shouldFallback: true,
|
||||
cooldownMs: COOLDOWN_MS.requestNotAllowed,
|
||||
reason: RateLimitReason.RATE_LIMIT_EXCEEDED,
|
||||
};
|
||||
}
|
||||
|
||||
// Rate limit keywords - exponential backoff
|
||||
if (
|
||||
lowerError.includes("rate limit") ||
|
||||
lowerError.includes("too many requests") ||
|
||||
lowerError.includes("quota exceeded") ||
|
||||
lowerError.includes("capacity") ||
|
||||
lowerError.includes("overloaded")
|
||||
) {
|
||||
const newLevel = Math.min(backoffLevel + 1, BACKOFF_CONFIG.maxLevel);
|
||||
const reason = classifyErrorText(errorStr);
|
||||
return {
|
||||
shouldFallback: true,
|
||||
cooldownMs: getQuotaCooldown(backoffLevel),
|
||||
newBackoffLevel: newLevel,
|
||||
reason,
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
if (status === HTTP_STATUS.UNAUTHORIZED) {
|
||||
return {
|
||||
shouldFallback: true,
|
||||
cooldownMs: COOLDOWN_MS.unauthorized,
|
||||
reason: RateLimitReason.AUTH_ERROR,
|
||||
};
|
||||
}
|
||||
|
||||
if (status === HTTP_STATUS.PAYMENT_REQUIRED || status === HTTP_STATUS.FORBIDDEN) {
|
||||
return {
|
||||
shouldFallback: true,
|
||||
cooldownMs: COOLDOWN_MS.paymentRequired,
|
||||
reason: RateLimitReason.QUOTA_EXHAUSTED,
|
||||
};
|
||||
}
|
||||
|
||||
if (status === HTTP_STATUS.NOT_FOUND) {
|
||||
return {
|
||||
shouldFallback: true,
|
||||
cooldownMs: COOLDOWN_MS.notFound,
|
||||
reason: RateLimitReason.UNKNOWN,
|
||||
};
|
||||
}
|
||||
|
||||
// 429 - Rate limit with exponential backoff
|
||||
if (status === HTTP_STATUS.RATE_LIMITED) {
|
||||
const newLevel = Math.min(backoffLevel + 1, BACKOFF_CONFIG.maxLevel);
|
||||
return {
|
||||
shouldFallback: true,
|
||||
cooldownMs: getQuotaCooldown(backoffLevel),
|
||||
newBackoffLevel: newLevel,
|
||||
reason: RateLimitReason.RATE_LIMIT_EXCEEDED,
|
||||
};
|
||||
}
|
||||
|
||||
// Transient / server errors — exponential backoff with provider profile
|
||||
const transientStatuses = [
|
||||
HTTP_STATUS.NOT_ACCEPTABLE,
|
||||
HTTP_STATUS.REQUEST_TIMEOUT,
|
||||
HTTP_STATUS.SERVER_ERROR,
|
||||
HTTP_STATUS.BAD_GATEWAY,
|
||||
HTTP_STATUS.SERVICE_UNAVAILABLE,
|
||||
HTTP_STATUS.GATEWAY_TIMEOUT,
|
||||
];
|
||||
if (transientStatuses.includes(status)) {
|
||||
const profile = provider ? getProviderProfile(provider) : null;
|
||||
const baseCooldown = profile?.transientCooldown ?? COOLDOWN_MS.transientInitial;
|
||||
const maxLevel = profile?.maxBackoffLevel ?? BACKOFF_CONFIG.maxLevel;
|
||||
const cooldownMs = Math.min(baseCooldown * Math.pow(2, backoffLevel), COOLDOWN_MS.transientMax);
|
||||
const newLevel = Math.min(backoffLevel + 1, maxLevel);
|
||||
return {
|
||||
shouldFallback: true,
|
||||
cooldownMs,
|
||||
newBackoffLevel: newLevel,
|
||||
reason: RateLimitReason.SERVER_ERROR,
|
||||
};
|
||||
}
|
||||
|
||||
// 400 Bad Request - don't fallback (same request will fail on all accounts)
|
||||
if (status === HTTP_STATUS.BAD_REQUEST) {
|
||||
return { shouldFallback: false, cooldownMs: 0, reason: RateLimitReason.UNKNOWN };
|
||||
}
|
||||
|
||||
// All other errors - fallback with transient cooldown
|
||||
return {
|
||||
shouldFallback: true,
|
||||
cooldownMs: COOLDOWN_MS.transient,
|
||||
reason: RateLimitReason.UNKNOWN,
|
||||
};
|
||||
}
|
||||
|
||||
// ─── Account State Management ───────────────────────────────────────────────
|
||||
|
||||
/**
|
||||
* Check if account is currently unavailable (cooldown not expired)
|
||||
*/
|
||||
export function isAccountUnavailable(unavailableUntil) {
|
||||
if (!unavailableUntil) return false;
|
||||
return new Date(unavailableUntil).getTime() > Date.now();
|
||||
}
|
||||
|
||||
/**
|
||||
* Calculate unavailable until timestamp
|
||||
*/
|
||||
export function getUnavailableUntil(cooldownMs) {
|
||||
return new Date(Date.now() + cooldownMs).toISOString();
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the earliest rateLimitedUntil from a list of accounts
|
||||
*/
|
||||
export function getEarliestRateLimitedUntil(accounts) {
|
||||
let earliest = null;
|
||||
const now = Date.now();
|
||||
for (const acc of accounts) {
|
||||
if (!acc.rateLimitedUntil) continue;
|
||||
const until = new Date(acc.rateLimitedUntil).getTime();
|
||||
if (until <= now) continue;
|
||||
if (!earliest || until < earliest) earliest = until;
|
||||
}
|
||||
if (!earliest) return null;
|
||||
return new Date(earliest).toISOString();
|
||||
}
|
||||
|
||||
/**
|
||||
* Format rateLimitedUntil to human-readable "reset after Xm Ys"
|
||||
*/
|
||||
export function formatRetryAfter(rateLimitedUntil) {
|
||||
if (!rateLimitedUntil) return "";
|
||||
const diffMs = new Date(rateLimitedUntil).getTime() - Date.now();
|
||||
if (diffMs <= 0) return "reset after 0s";
|
||||
const totalSec = Math.ceil(diffMs / 1000);
|
||||
const h = Math.floor(totalSec / 3600);
|
||||
const m = Math.floor((totalSec % 3600) / 60);
|
||||
const s = totalSec % 60;
|
||||
const parts = [];
|
||||
if (h > 0) parts.push(`${h}h`);
|
||||
if (m > 0) parts.push(`${m}m`);
|
||||
if (s > 0 || parts.length === 0) parts.push(`${s}s`);
|
||||
return `reset after ${parts.join(" ")}`;
|
||||
}
|
||||
|
||||
/**
|
||||
* Filter available accounts (not in cooldown)
|
||||
*/
|
||||
export function filterAvailableAccounts(accounts, excludeId = null) {
|
||||
const now = Date.now();
|
||||
return accounts.filter((acc) => {
|
||||
if (excludeId && acc.id === excludeId) return false;
|
||||
if (acc.rateLimitedUntil) {
|
||||
const until = new Date(acc.rateLimitedUntil).getTime();
|
||||
if (until > now) return false;
|
||||
}
|
||||
return true;
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Reset account state when request succeeds
|
||||
*/
|
||||
export function resetAccountState(account) {
|
||||
if (!account) return account;
|
||||
return {
|
||||
...account,
|
||||
rateLimitedUntil: null,
|
||||
backoffLevel: 0,
|
||||
lastError: null,
|
||||
status: "active",
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Apply error state to account
|
||||
*/
|
||||
export function applyErrorState(account, status, errorText, provider = null) {
|
||||
if (!account) return account;
|
||||
|
||||
const backoffLevel = account.backoffLevel || 0;
|
||||
const { cooldownMs, newBackoffLevel, reason } = checkFallbackError(
|
||||
status,
|
||||
errorText,
|
||||
backoffLevel,
|
||||
null,
|
||||
provider
|
||||
);
|
||||
|
||||
return {
|
||||
...account,
|
||||
rateLimitedUntil: cooldownMs > 0 ? getUnavailableUntil(cooldownMs) : null,
|
||||
backoffLevel: newBackoffLevel ?? backoffLevel,
|
||||
lastError: { status, message: errorText, timestamp: new Date().toISOString(), reason },
|
||||
status: "error",
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Get account health score (0-100) for P2C selection (Phase 9)
|
||||
* @param {object} account
|
||||
* @returns {number} score 0 = unhealthy, 100 = perfectly healthy
|
||||
*/
|
||||
export function getAccountHealth(account, model?: any) {
|
||||
if (!account) return 0;
|
||||
let score = 100;
|
||||
score -= (account.backoffLevel || 0) * 10;
|
||||
if (account.lastError) score -= 20;
|
||||
if (account.rateLimitedUntil && isAccountUnavailable(account.rateLimitedUntil)) score -= 30;
|
||||
return Math.max(0, score);
|
||||
}
|
||||
74
open-sse/services/accountSelector.ts
Normal file
74
open-sse/services/accountSelector.ts
Normal file
@@ -0,0 +1,74 @@
|
||||
/**
|
||||
* Quota-Aware Account Selection (P2C) — Phase 9
|
||||
*
|
||||
* Power of Two Choices: pick 2 random accounts, select the healthier one.
|
||||
* Uses account health scores from accountFallback.js.
|
||||
*/
|
||||
|
||||
import { getAccountHealth } from "./accountFallback.ts";
|
||||
|
||||
/**
|
||||
* P2C selection: pick 2 random candidates, return the healthier one.
|
||||
* Falls back to random if only 1 candidate.
|
||||
*
|
||||
* @param {Array} accounts - Available account objects
|
||||
* @param {string} [model] - Model name (for model-specific health check)
|
||||
* @returns {object|null} Selected account
|
||||
*/
|
||||
export function selectAccountP2C(accounts, model = null) {
|
||||
if (!accounts || accounts.length === 0) return null;
|
||||
if (accounts.length === 1) return accounts[0];
|
||||
|
||||
// Pick 2 random distinct indices
|
||||
const i = Math.floor(Math.random() * accounts.length);
|
||||
let j = Math.floor(Math.random() * (accounts.length - 1));
|
||||
if (j >= i) j++; // Ensure distinct
|
||||
|
||||
const a = accounts[i];
|
||||
const b = accounts[j];
|
||||
|
||||
const healthA = getAccountHealth(a, model);
|
||||
const healthB = getAccountHealth(b, model);
|
||||
|
||||
return healthA >= healthB ? a : b;
|
||||
}
|
||||
|
||||
/**
|
||||
* Select account with strategy support.
|
||||
* Integrates P2C as a new strategy alongside existing fill-first and round-robin.
|
||||
*
|
||||
* @param {Array} accounts - Available accounts
|
||||
* @param {string} strategy - "fill-first" | "round-robin" | "p2c" | "random"
|
||||
* @param {object} [state] - Strategy state (e.g., lastIndex for round-robin)
|
||||
* @param {string} [model] - Model name
|
||||
* @returns {{ account: object|null, state: object }}
|
||||
*/
|
||||
export function selectAccount(accounts, strategy = "fill-first", state: any = {}, model = null) {
|
||||
if (!accounts || accounts.length === 0) {
|
||||
return { account: null, state };
|
||||
}
|
||||
|
||||
switch (strategy) {
|
||||
case "p2c":
|
||||
return { account: selectAccountP2C(accounts, model), state };
|
||||
|
||||
case "random":
|
||||
return {
|
||||
account: accounts[Math.floor(Math.random() * accounts.length)],
|
||||
state,
|
||||
};
|
||||
|
||||
case "round-robin": {
|
||||
const lastIndex = state.lastIndex ?? -1;
|
||||
const nextIndex = (lastIndex + 1) % accounts.length;
|
||||
return {
|
||||
account: accounts[nextIndex],
|
||||
state: { ...state, lastIndex: nextIndex },
|
||||
};
|
||||
}
|
||||
|
||||
case "fill-first":
|
||||
default:
|
||||
return { account: accounts[0], state };
|
||||
}
|
||||
}
|
||||
723
open-sse/services/combo.ts
Normal file
723
open-sse/services/combo.ts
Normal file
@@ -0,0 +1,723 @@
|
||||
/**
|
||||
* Shared combo (model combo) handling with fallback support
|
||||
* Supports: priority, weighted, round-robin, random, least-used, and cost-optimized strategies
|
||||
*/
|
||||
|
||||
import { checkFallbackError, formatRetryAfter, getProviderProfile } from "./accountFallback.ts";
|
||||
import { unavailableResponse } from "../utils/error.ts";
|
||||
import { recordComboRequest, getComboMetrics } from "./comboMetrics.ts";
|
||||
import { resolveComboConfig, getDefaultComboConfig } from "./comboConfig.ts";
|
||||
import * as semaphore from "./rateLimitSemaphore.ts";
|
||||
import { getCircuitBreaker } from "../../src/shared/utils/circuitBreaker";
|
||||
import { parseModel } from "./model.ts";
|
||||
|
||||
// Status codes that should mark semaphore + record circuit breaker failures
|
||||
const TRANSIENT_FOR_BREAKER = [429, 502, 503, 504];
|
||||
|
||||
const MAX_COMBO_DEPTH = 3;
|
||||
|
||||
// In-memory atomic counter per combo for round-robin distribution
|
||||
// Resets on server restart (by design — no stale state)
|
||||
const rrCounters = new Map();
|
||||
|
||||
/**
|
||||
* Normalize a model entry to { model, weight }
|
||||
* Supports both legacy string format and new object format
|
||||
*/
|
||||
function normalizeModelEntry(entry) {
|
||||
if (typeof entry === "string") return { model: entry, weight: 0 };
|
||||
return { model: entry.model, weight: entry.weight || 0 };
|
||||
}
|
||||
|
||||
/**
|
||||
* Get combo models from combos data (for open-sse standalone use)
|
||||
* @param {string} modelStr - Model string to check
|
||||
* @param {Array|Object} combosData - Array of combos or object with combos
|
||||
* @returns {Object|null} Full combo object or null if not a combo
|
||||
*/
|
||||
export function getComboFromData(modelStr, combosData) {
|
||||
const combos = Array.isArray(combosData) ? combosData : combosData?.combos || [];
|
||||
const combo = combos.find((c) => c.name === modelStr);
|
||||
if (combo && combo.models && combo.models.length > 0) {
|
||||
return combo;
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Legacy: Get combo models as string array (backward compat)
|
||||
*/
|
||||
export function getComboModelsFromData(modelStr, combosData) {
|
||||
const combo = getComboFromData(modelStr, combosData);
|
||||
if (!combo) return null;
|
||||
return combo.models.map((m) => normalizeModelEntry(m).model);
|
||||
}
|
||||
|
||||
/**
|
||||
* Validate combo DAG — detect circular references and enforce max depth
|
||||
* @param {string} comboName - Name of the combo to validate
|
||||
* @param {Array} allCombos - All combos in the system
|
||||
* @param {Set} [visited] - Set of already visited combo names (for cycle detection)
|
||||
* @param {number} [depth] - Current depth level
|
||||
* @throws {Error} If circular reference or max depth exceeded
|
||||
*/
|
||||
export function validateComboDAG(comboName, allCombos, visited = new Set(), depth = 0) {
|
||||
if (depth > MAX_COMBO_DEPTH) {
|
||||
throw new Error(`Max combo nesting depth (${MAX_COMBO_DEPTH}) exceeded at "${comboName}"`);
|
||||
}
|
||||
if (visited.has(comboName)) {
|
||||
throw new Error(`Circular combo reference detected: ${comboName}`);
|
||||
}
|
||||
visited.add(comboName);
|
||||
|
||||
const combos = Array.isArray(allCombos) ? allCombos : allCombos?.combos || [];
|
||||
const combo = combos.find((c) => c.name === comboName);
|
||||
if (!combo || !combo.models) return;
|
||||
|
||||
for (const entry of combo.models) {
|
||||
const modelName = normalizeModelEntry(entry).model;
|
||||
// Check if this model name is itself a combo (not a provider/model pattern)
|
||||
const nestedCombo = combos.find((c) => c.name === modelName);
|
||||
if (nestedCombo) {
|
||||
validateComboDAG(modelName, combos, new Set(visited), depth + 1);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Resolve nested combos by expanding inline to a flat model list
|
||||
* Respects max depth and detects cycles
|
||||
* @param {Object} combo - The combo object
|
||||
* @param {Array} allCombos - All combos in the system
|
||||
* @param {Set} [visited] - For cycle detection
|
||||
* @param {number} [depth] - Current depth
|
||||
* @returns {Array} Flat array of model strings
|
||||
*/
|
||||
export function resolveNestedComboModels(combo, allCombos, visited = new Set(), depth = 0) {
|
||||
if (depth > MAX_COMBO_DEPTH) return combo.models.map((m) => normalizeModelEntry(m).model);
|
||||
if (visited.has(combo.name)) return []; // cycle safety
|
||||
visited.add(combo.name);
|
||||
|
||||
const combos = Array.isArray(allCombos) ? allCombos : allCombos?.combos || [];
|
||||
const resolved = [];
|
||||
|
||||
for (const entry of combo.models || []) {
|
||||
const modelName = normalizeModelEntry(entry).model;
|
||||
const nestedCombo = combos.find((c) => c.name === modelName);
|
||||
|
||||
if (nestedCombo) {
|
||||
// Recursively expand the nested combo
|
||||
const nested = resolveNestedComboModels(nestedCombo, combos, new Set(visited), depth + 1);
|
||||
resolved.push(...nested);
|
||||
} else {
|
||||
resolved.push(modelName);
|
||||
}
|
||||
}
|
||||
|
||||
return resolved;
|
||||
}
|
||||
|
||||
/**
|
||||
* Select a model using weighted random distribution
|
||||
* @param {Array} models - Array of { model, weight } entries
|
||||
* @returns {string} Selected model string
|
||||
*/
|
||||
function selectWeightedModel(models) {
|
||||
const entries = models.map((m) => normalizeModelEntry(m));
|
||||
const totalWeight = entries.reduce((sum, m) => sum + m.weight, 0);
|
||||
|
||||
if (totalWeight <= 0) {
|
||||
// All weights are 0 → uniform random
|
||||
return entries[Math.floor(Math.random() * entries.length)].model;
|
||||
}
|
||||
|
||||
let random = Math.random() * totalWeight;
|
||||
for (const entry of entries) {
|
||||
random -= entry.weight;
|
||||
if (random <= 0) return entry.model;
|
||||
}
|
||||
return entries[entries.length - 1].model; // safety fallback
|
||||
}
|
||||
|
||||
/**
|
||||
* Order models for weighted fallback (selected first, then by descending weight)
|
||||
*/
|
||||
function orderModelsForWeightedFallback(models, selectedModel) {
|
||||
const entries = models.map((m) => normalizeModelEntry(m));
|
||||
const selected = entries.find((e) => e.model === selectedModel);
|
||||
const rest = entries.filter((e) => e.model !== selectedModel).sort((a, b) => b.weight - a.weight); // highest weight first for fallback
|
||||
|
||||
return [selected, ...rest].filter(Boolean).map((e) => e.model);
|
||||
}
|
||||
|
||||
/**
|
||||
* Fisher-Yates shuffle (in-place)
|
||||
* @param {Array} arr
|
||||
* @returns {Array} The shuffled array
|
||||
*/
|
||||
function shuffleArray(arr) {
|
||||
for (let i = arr.length - 1; i > 0; i--) {
|
||||
const j = Math.floor(Math.random() * (i + 1));
|
||||
[arr[i], arr[j]] = [arr[j], arr[i]];
|
||||
}
|
||||
return arr;
|
||||
}
|
||||
|
||||
/**
|
||||
* Sort models by pricing (cheapest first) for cost-optimized strategy
|
||||
* @param {Array<string>} models - Model strings in "provider/model" format
|
||||
* @returns {Promise<Array<string>>} Sorted model strings
|
||||
*/
|
||||
async function sortModelsByCost(models) {
|
||||
try {
|
||||
const { getPricingForModel } = await import("../../src/lib/localDb");
|
||||
const withCost = await Promise.all(
|
||||
models.map(async (modelStr) => {
|
||||
const parsed = parseModel(modelStr);
|
||||
const provider = parsed.provider || parsed.providerAlias || "unknown";
|
||||
const model = parsed.model || modelStr;
|
||||
try {
|
||||
const pricing = await getPricingForModel(provider, model);
|
||||
return { modelStr, cost: pricing?.input ?? Infinity };
|
||||
} catch {
|
||||
return { modelStr, cost: Infinity };
|
||||
}
|
||||
})
|
||||
);
|
||||
withCost.sort((a, b) => a.cost - b.cost);
|
||||
return withCost.map((e) => e.modelStr);
|
||||
} catch {
|
||||
// If pricing lookup fails entirely, return original order
|
||||
return models;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Sort models by usage count (least-used first) for least-used strategy
|
||||
* @param {Array<string>} models - Model strings
|
||||
* @param {string} comboName - Combo name for metrics lookup
|
||||
* @returns {Array<string>} Sorted model strings
|
||||
*/
|
||||
function sortModelsByUsage(models, comboName) {
|
||||
const metrics = getComboMetrics(comboName);
|
||||
if (!metrics || !metrics.byModel) return models;
|
||||
|
||||
const withUsage = models.map((modelStr) => ({
|
||||
modelStr,
|
||||
requests: metrics.byModel[modelStr]?.requests ?? 0,
|
||||
}));
|
||||
withUsage.sort((a, b) => a.requests - b.requests);
|
||||
return withUsage.map((e) => e.modelStr);
|
||||
}
|
||||
|
||||
/**
|
||||
* Handle combo chat with fallback
|
||||
* Supports all 6 strategies: priority, weighted, round-robin, random, least-used, cost-optimized
|
||||
* @param {Object} options
|
||||
* @param {Object} options.body - Request body
|
||||
* @param {Object} options.combo - Full combo object { name, models, strategy, config }
|
||||
* @param {Function} options.handleSingleModel - Function: (body, modelStr) => Promise<Response>
|
||||
* @param {Function} [options.isModelAvailable] - Optional pre-check: (modelStr) => Promise<boolean>
|
||||
* @param {Object} options.log - Logger object
|
||||
* @returns {Promise<Response>}
|
||||
*/
|
||||
/** @param {any} options */
|
||||
export async function handleComboChat({
|
||||
body,
|
||||
combo,
|
||||
handleSingleModel,
|
||||
isModelAvailable,
|
||||
log,
|
||||
settings,
|
||||
allCombos,
|
||||
}) {
|
||||
const strategy = combo.strategy || "priority";
|
||||
const models = combo.models || [];
|
||||
|
||||
// Route to round-robin handler if strategy matches
|
||||
if (strategy === "round-robin") {
|
||||
return handleRoundRobinCombo({
|
||||
body,
|
||||
combo,
|
||||
handleSingleModel,
|
||||
isModelAvailable,
|
||||
log,
|
||||
settings,
|
||||
allCombos,
|
||||
});
|
||||
}
|
||||
|
||||
// Use config cascade if settings provided
|
||||
const config = settings
|
||||
? resolveComboConfig(combo, settings)
|
||||
: { ...getDefaultComboConfig(), ...(combo.config || {}) };
|
||||
const maxRetries = config.maxRetries ?? 1;
|
||||
const retryDelayMs = config.retryDelayMs ?? 2000;
|
||||
|
||||
let orderedModels;
|
||||
|
||||
// Resolve nested combos if allCombos provided
|
||||
if (allCombos) {
|
||||
const flatModels = resolveNestedComboModels(combo, allCombos);
|
||||
if (strategy === "weighted") {
|
||||
// For weighted + nested, select from original models then fallback sequentially
|
||||
const selected = selectWeightedModel(models);
|
||||
orderedModels = orderModelsForWeightedFallback(models, selected);
|
||||
// But if any were nested, they are already resolved to flat
|
||||
orderedModels = orderedModels.flatMap((m) => {
|
||||
const combos = Array.isArray(allCombos) ? allCombos : allCombos?.combos || [];
|
||||
const nested = combos.find((c) => c.name === m);
|
||||
if (nested) return resolveNestedComboModels(nested, allCombos);
|
||||
return [m];
|
||||
});
|
||||
log.info(
|
||||
"COMBO",
|
||||
`Weighted selection with nested resolution: ${orderedModels.length} total models`
|
||||
);
|
||||
} else {
|
||||
orderedModels = flatModels;
|
||||
log.info("COMBO", `${strategy} with nested resolution: ${orderedModels.length} total models`);
|
||||
}
|
||||
} else if (strategy === "weighted") {
|
||||
const selected = selectWeightedModel(models);
|
||||
orderedModels = orderModelsForWeightedFallback(models, selected);
|
||||
log.info("COMBO", `Weighted selection: ${selected} (from ${models.length} models)`);
|
||||
} else {
|
||||
orderedModels = models.map((m) => normalizeModelEntry(m).model);
|
||||
}
|
||||
|
||||
// Apply strategy-specific ordering
|
||||
if (strategy === "random") {
|
||||
orderedModels = shuffleArray([...orderedModels]);
|
||||
log.info("COMBO", `Random shuffle: ${orderedModels.length} models`);
|
||||
} else if (strategy === "least-used") {
|
||||
orderedModels = sortModelsByUsage(orderedModels, combo.name);
|
||||
log.info("COMBO", `Least-used ordering: ${orderedModels[0]} has fewest requests`);
|
||||
} else if (strategy === "cost-optimized") {
|
||||
orderedModels = await sortModelsByCost(orderedModels);
|
||||
log.info("COMBO", `Cost-optimized ordering: cheapest first (${orderedModels[0]})`);
|
||||
}
|
||||
|
||||
let lastError = null;
|
||||
let earliestRetryAfter = null;
|
||||
let lastStatus = null;
|
||||
const startTime = Date.now();
|
||||
let resolvedByModel = null;
|
||||
let fallbackCount = 0;
|
||||
|
||||
for (let i = 0; i < orderedModels.length; i++) {
|
||||
const modelStr = orderedModels[i];
|
||||
const parsed = parseModel(modelStr);
|
||||
const provider = parsed.provider || parsed.providerAlias || "unknown";
|
||||
const profile = getProviderProfile(provider);
|
||||
const breaker = getCircuitBreaker(`combo:${provider}`, {
|
||||
failureThreshold: profile.circuitBreakerThreshold,
|
||||
resetTimeout: profile.circuitBreakerReset,
|
||||
});
|
||||
|
||||
// Skip model if circuit breaker is OPEN
|
||||
if (!breaker.canExecute()) {
|
||||
log.info("COMBO", `Skipping ${modelStr}: circuit breaker OPEN for ${provider}`);
|
||||
if (i > 0) fallbackCount++;
|
||||
continue;
|
||||
}
|
||||
|
||||
// Pre-check: skip models where all accounts are in cooldown
|
||||
if (isModelAvailable) {
|
||||
const available = await isModelAvailable(modelStr);
|
||||
if (!available) {
|
||||
log.info("COMBO", `Skipping ${modelStr} (all accounts in cooldown)`);
|
||||
if (i > 0) fallbackCount++;
|
||||
continue;
|
||||
}
|
||||
}
|
||||
|
||||
// Retry loop for transient errors
|
||||
for (let retry = 0; retry <= maxRetries; retry++) {
|
||||
if (retry > 0) {
|
||||
log.info(
|
||||
"COMBO",
|
||||
`Retrying ${modelStr} in ${retryDelayMs}ms (attempt ${retry + 1}/${maxRetries + 1})`
|
||||
);
|
||||
await new Promise((r) => setTimeout(r, retryDelayMs));
|
||||
}
|
||||
|
||||
log.info(
|
||||
"COMBO",
|
||||
`Trying model ${i + 1}/${orderedModels.length}: ${modelStr}${retry > 0 ? ` (retry ${retry})` : ""}`
|
||||
);
|
||||
|
||||
const result = await handleSingleModel(body, modelStr);
|
||||
|
||||
// Success — return response
|
||||
if (result.ok) {
|
||||
resolvedByModel = modelStr;
|
||||
const latencyMs = Date.now() - startTime;
|
||||
log.info(
|
||||
"COMBO",
|
||||
`Model ${modelStr} succeeded (${latencyMs}ms, ${fallbackCount} fallbacks)`
|
||||
);
|
||||
recordComboRequest(combo.name, modelStr, {
|
||||
success: true,
|
||||
latencyMs,
|
||||
fallbackCount,
|
||||
strategy,
|
||||
});
|
||||
return result;
|
||||
}
|
||||
|
||||
// Extract error info from response
|
||||
let errorText = result.statusText || "";
|
||||
let retryAfter = null;
|
||||
try {
|
||||
const cloned = result.clone();
|
||||
try {
|
||||
const errorBody = await cloned.json();
|
||||
errorText =
|
||||
errorBody?.error?.message || errorBody?.error || errorBody?.message || errorText;
|
||||
retryAfter = errorBody?.retryAfter || null;
|
||||
} catch {
|
||||
try {
|
||||
const text = await result.text();
|
||||
if (text) errorText = text.substring(0, 500);
|
||||
} catch {
|
||||
/* Body consumed */
|
||||
}
|
||||
}
|
||||
} catch {
|
||||
/* Clone failed */
|
||||
}
|
||||
|
||||
// Track earliest retryAfter
|
||||
if (
|
||||
retryAfter &&
|
||||
(!earliestRetryAfter || new Date(retryAfter) < new Date(earliestRetryAfter))
|
||||
) {
|
||||
earliestRetryAfter = retryAfter;
|
||||
}
|
||||
|
||||
// Normalize error text
|
||||
if (typeof errorText !== "string") {
|
||||
try {
|
||||
errorText = JSON.stringify(errorText);
|
||||
} catch {
|
||||
errorText = String(errorText);
|
||||
}
|
||||
}
|
||||
|
||||
const { shouldFallback, cooldownMs } = checkFallbackError(
|
||||
result.status,
|
||||
errorText,
|
||||
0,
|
||||
null,
|
||||
provider
|
||||
);
|
||||
|
||||
// Record failure in circuit breaker for transient errors
|
||||
if (TRANSIENT_FOR_BREAKER.includes(result.status)) {
|
||||
breaker._onFailure();
|
||||
}
|
||||
|
||||
if (!shouldFallback) {
|
||||
log.warn("COMBO", `Model ${modelStr} failed (no fallback)`, { status: result.status });
|
||||
return result;
|
||||
}
|
||||
|
||||
// Check if this is a transient error worth retrying on same model
|
||||
const isTransient = [408, 429, 500, 502, 503, 504].includes(result.status);
|
||||
if (retry < maxRetries && isTransient) {
|
||||
continue; // Retry same model
|
||||
}
|
||||
|
||||
// Done retrying this model
|
||||
lastError = errorText || String(result.status);
|
||||
if (!lastStatus) lastStatus = result.status;
|
||||
if (i > 0) fallbackCount++;
|
||||
log.warn("COMBO", `Model ${modelStr} failed, trying next`, { status: result.status });
|
||||
break; // Move to next model
|
||||
}
|
||||
}
|
||||
|
||||
// Early exit: check if all models have breaker OPEN
|
||||
const allBreakersOpen = orderedModels.every((m) => {
|
||||
const p = parseModel(m).provider || parseModel(m).providerAlias || "unknown";
|
||||
return !getCircuitBreaker(`combo:${p}`).canExecute();
|
||||
});
|
||||
|
||||
// All models failed
|
||||
const latencyMs = Date.now() - startTime;
|
||||
recordComboRequest(combo.name, null, { success: false, latencyMs, fallbackCount, strategy });
|
||||
|
||||
if (allBreakersOpen) {
|
||||
log.warn("COMBO", "All models have circuit breaker OPEN — aborting");
|
||||
return unavailableResponse(
|
||||
503,
|
||||
"All providers temporarily unavailable (circuit breakers open)"
|
||||
);
|
||||
}
|
||||
|
||||
const status = lastStatus || 406;
|
||||
const msg = lastError || "All combo models unavailable";
|
||||
|
||||
if (earliestRetryAfter) {
|
||||
const retryHuman = formatRetryAfter(earliestRetryAfter);
|
||||
log.warn("COMBO", `All models failed | ${msg} (${retryHuman})`);
|
||||
return unavailableResponse(status, msg, earliestRetryAfter, retryHuman);
|
||||
}
|
||||
|
||||
log.warn("COMBO", `All models failed | ${msg}`);
|
||||
return new Response(JSON.stringify({ error: { message: msg } }), {
|
||||
status,
|
||||
headers: { "Content-Type": "application/json" },
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Handle round-robin combo: each request goes to the next model in circular order.
|
||||
* Uses semaphore-based concurrency control with queue + rate-limit awareness.
|
||||
*
|
||||
* Flow:
|
||||
* 1. Pick target model via atomic counter (counter % models.length)
|
||||
* 2. Acquire semaphore slot (may queue if at max concurrency)
|
||||
* 3. Send request to target model
|
||||
* 4. On 429 → mark model rate-limited, try next model in rotation
|
||||
* 5. On semaphore timeout → fallback to next available model
|
||||
*/
|
||||
async function handleRoundRobinCombo({
|
||||
body,
|
||||
combo,
|
||||
handleSingleModel,
|
||||
isModelAvailable,
|
||||
log,
|
||||
settings,
|
||||
allCombos,
|
||||
}) {
|
||||
const models = combo.models || [];
|
||||
const config = settings
|
||||
? resolveComboConfig(combo, settings)
|
||||
: { ...getDefaultComboConfig(), ...(combo.config || {}) };
|
||||
const concurrency = config.concurrencyPerModel ?? 3;
|
||||
const queueTimeout = config.queueTimeoutMs ?? 30000;
|
||||
const maxRetries = config.maxRetries ?? 1;
|
||||
const retryDelayMs = config.retryDelayMs ?? 2000;
|
||||
|
||||
// Resolve models (support nested combos)
|
||||
let orderedModels;
|
||||
if (allCombos) {
|
||||
orderedModels = resolveNestedComboModels(combo, allCombos);
|
||||
} else {
|
||||
orderedModels = models.map((m) => normalizeModelEntry(m).model);
|
||||
}
|
||||
|
||||
const modelCount = orderedModels.length;
|
||||
if (modelCount === 0) {
|
||||
return unavailableResponse(406, "Round-robin combo has no models");
|
||||
}
|
||||
|
||||
// Get and increment atomic counter
|
||||
const counter = rrCounters.get(combo.name) || 0;
|
||||
rrCounters.set(combo.name, counter + 1);
|
||||
const startIndex = counter % modelCount;
|
||||
|
||||
const startTime = Date.now();
|
||||
let lastError = null;
|
||||
let lastStatus = null;
|
||||
let earliestRetryAfter = null;
|
||||
let fallbackCount = 0;
|
||||
|
||||
// Try each model starting from the round-robin target
|
||||
for (let offset = 0; offset < modelCount; offset++) {
|
||||
const modelIndex = (startIndex + offset) % modelCount;
|
||||
const modelStr = orderedModels[modelIndex];
|
||||
const parsed = parseModel(modelStr);
|
||||
const provider = parsed.provider || parsed.providerAlias || "unknown";
|
||||
const profile = getProviderProfile(provider);
|
||||
const breaker = getCircuitBreaker(`combo:${provider}`, {
|
||||
failureThreshold: profile.circuitBreakerThreshold,
|
||||
resetTimeout: profile.circuitBreakerReset,
|
||||
});
|
||||
|
||||
// Skip model if circuit breaker is OPEN
|
||||
if (!breaker.canExecute()) {
|
||||
log.info("COMBO-RR", `Skipping ${modelStr}: circuit breaker OPEN for ${provider}`);
|
||||
if (offset > 0) fallbackCount++;
|
||||
continue;
|
||||
}
|
||||
|
||||
// Pre-check availability
|
||||
if (isModelAvailable) {
|
||||
const available = await isModelAvailable(modelStr);
|
||||
if (!available) {
|
||||
log.info("COMBO-RR", `Skipping ${modelStr} (all accounts in cooldown)`);
|
||||
if (offset > 0) fallbackCount++;
|
||||
continue;
|
||||
}
|
||||
}
|
||||
|
||||
// Acquire semaphore slot (may wait in queue)
|
||||
let release;
|
||||
try {
|
||||
release = await semaphore.acquire(modelStr, {
|
||||
maxConcurrency: concurrency,
|
||||
timeoutMs: queueTimeout,
|
||||
});
|
||||
} catch (err) {
|
||||
if (err.code === "SEMAPHORE_TIMEOUT") {
|
||||
log.warn("COMBO-RR", `Semaphore timeout for ${modelStr}, trying next model`);
|
||||
if (offset > 0) fallbackCount++;
|
||||
continue;
|
||||
}
|
||||
throw err;
|
||||
}
|
||||
|
||||
// Retry loop within this model
|
||||
try {
|
||||
for (let retry = 0; retry <= maxRetries; retry++) {
|
||||
if (retry > 0) {
|
||||
log.info(
|
||||
"COMBO-RR",
|
||||
`Retrying ${modelStr} in ${retryDelayMs}ms (attempt ${retry + 1}/${maxRetries + 1})`
|
||||
);
|
||||
await new Promise((r) => setTimeout(r, retryDelayMs));
|
||||
}
|
||||
|
||||
log.info(
|
||||
"COMBO-RR",
|
||||
`[RR #${counter}] → ${modelStr}${offset > 0 ? ` (fallback +${offset})` : ""}${retry > 0 ? ` (retry ${retry})` : ""}`
|
||||
);
|
||||
|
||||
const result = await handleSingleModel(body, modelStr);
|
||||
|
||||
// Success
|
||||
if (result.ok) {
|
||||
const latencyMs = Date.now() - startTime;
|
||||
log.info(
|
||||
"COMBO-RR",
|
||||
`${modelStr} succeeded (${latencyMs}ms, ${fallbackCount} fallbacks)`
|
||||
);
|
||||
recordComboRequest(combo.name, modelStr, {
|
||||
success: true,
|
||||
latencyMs,
|
||||
fallbackCount,
|
||||
strategy: "round-robin",
|
||||
});
|
||||
return result;
|
||||
}
|
||||
|
||||
// Extract error info
|
||||
let errorText = result.statusText || "";
|
||||
let retryAfter = null;
|
||||
try {
|
||||
const cloned = result.clone();
|
||||
try {
|
||||
const errorBody = await cloned.json();
|
||||
errorText =
|
||||
errorBody?.error?.message || errorBody?.error || errorBody?.message || errorText;
|
||||
retryAfter = errorBody?.retryAfter || null;
|
||||
} catch {
|
||||
try {
|
||||
const text = await result.text();
|
||||
if (text) errorText = text.substring(0, 500);
|
||||
} catch {
|
||||
/* Body consumed */
|
||||
}
|
||||
}
|
||||
} catch {
|
||||
/* Clone failed */
|
||||
}
|
||||
|
||||
if (
|
||||
retryAfter &&
|
||||
(!earliestRetryAfter || new Date(retryAfter) < new Date(earliestRetryAfter))
|
||||
) {
|
||||
earliestRetryAfter = retryAfter;
|
||||
}
|
||||
|
||||
if (typeof errorText !== "string") {
|
||||
try {
|
||||
errorText = JSON.stringify(errorText);
|
||||
} catch {
|
||||
errorText = String(errorText);
|
||||
}
|
||||
}
|
||||
|
||||
const { shouldFallback, cooldownMs } = checkFallbackError(
|
||||
result.status,
|
||||
errorText,
|
||||
0,
|
||||
null,
|
||||
provider
|
||||
);
|
||||
|
||||
// Transient errors → mark in semaphore AND record circuit breaker failure
|
||||
if (TRANSIENT_FOR_BREAKER.includes(result.status) && cooldownMs > 0) {
|
||||
semaphore.markRateLimited(modelStr, cooldownMs);
|
||||
breaker._onFailure();
|
||||
log.warn(
|
||||
"COMBO-RR",
|
||||
`${modelStr} error ${result.status}, cooldown ${cooldownMs}ms (breaker: ${breaker.getStatus().failureCount}/${profile.circuitBreakerThreshold})`
|
||||
);
|
||||
}
|
||||
|
||||
if (!shouldFallback) {
|
||||
log.warn("COMBO-RR", `${modelStr} failed (no fallback)`, { status: result.status });
|
||||
return result;
|
||||
}
|
||||
|
||||
// Transient error → retry same model
|
||||
const isTransient = [408, 429, 500, 502, 503, 504].includes(result.status);
|
||||
if (retry < maxRetries && isTransient) {
|
||||
continue;
|
||||
}
|
||||
|
||||
// Done with this model
|
||||
lastError = errorText || String(result.status);
|
||||
if (!lastStatus) lastStatus = result.status;
|
||||
if (offset > 0) fallbackCount++;
|
||||
log.warn("COMBO-RR", `${modelStr} failed, trying next model`, { status: result.status });
|
||||
break;
|
||||
}
|
||||
} finally {
|
||||
// ALWAYS release semaphore slot
|
||||
release();
|
||||
}
|
||||
}
|
||||
|
||||
// All models exhausted
|
||||
const latencyMs = Date.now() - startTime;
|
||||
recordComboRequest(combo.name, null, {
|
||||
success: false,
|
||||
latencyMs,
|
||||
fallbackCount,
|
||||
strategy: "round-robin",
|
||||
});
|
||||
|
||||
// Early exit: check if all models have breaker OPEN
|
||||
const allBreakersOpen = orderedModels.every((m) => {
|
||||
const p = parseModel(m).provider || parseModel(m).providerAlias || "unknown";
|
||||
return !getCircuitBreaker(`combo:${p}`).canExecute();
|
||||
});
|
||||
|
||||
if (allBreakersOpen) {
|
||||
log.warn("COMBO-RR", "All models have circuit breaker OPEN — aborting");
|
||||
return unavailableResponse(
|
||||
503,
|
||||
"All providers temporarily unavailable (circuit breakers open)"
|
||||
);
|
||||
}
|
||||
|
||||
const status = lastStatus || 406;
|
||||
const msg = lastError || "All round-robin combo models unavailable";
|
||||
|
||||
if (earliestRetryAfter) {
|
||||
const retryHuman = formatRetryAfter(earliestRetryAfter);
|
||||
log.warn("COMBO-RR", `All models failed | ${msg} (${retryHuman})`);
|
||||
return unavailableResponse(status, msg, earliestRetryAfter, retryHuman);
|
||||
}
|
||||
|
||||
log.warn("COMBO-RR", `All models failed | ${msg}`);
|
||||
return new Response(JSON.stringify({ error: { message: msg } }), {
|
||||
status,
|
||||
headers: { "Content-Type": "application/json" },
|
||||
});
|
||||
}
|
||||
52
open-sse/services/comboConfig.ts
Normal file
52
open-sse/services/comboConfig.ts
Normal file
@@ -0,0 +1,52 @@
|
||||
/**
|
||||
* Combo Configuration Resolver
|
||||
*
|
||||
* Implements 3-layer cascade: Global Defaults → Provider Overrides → Per-Combo Config
|
||||
* Most specific wins.
|
||||
*/
|
||||
|
||||
const DEFAULT_COMBO_CONFIG = {
|
||||
strategy: "priority",
|
||||
maxRetries: 1,
|
||||
retryDelayMs: 2000,
|
||||
timeoutMs: 120000,
|
||||
concurrencyPerModel: 3, // max simultaneous requests per model (round-robin)
|
||||
queueTimeoutMs: 30000, // max wait time in semaphore queue (round-robin)
|
||||
healthCheckEnabled: true,
|
||||
healthCheckTimeoutMs: 3000,
|
||||
maxComboDepth: 3,
|
||||
trackMetrics: true,
|
||||
};
|
||||
|
||||
/**
|
||||
* Resolve effective config for a combo, applying cascade:
|
||||
* DEFAULT_COMBO_CONFIG → settings.comboDefaults → settings.providerOverrides[provider] → combo.config
|
||||
*
|
||||
* @param {Object} combo - The combo object { config, ... }
|
||||
* @param {Object} settings - App settings from localDb
|
||||
* @param {string} [provider] - Optional provider to apply provider-level overrides
|
||||
* @returns {Object} Resolved config
|
||||
*/
|
||||
export function resolveComboConfig(combo, settings, provider?: any) {
|
||||
const global = settings?.comboDefaults || {};
|
||||
const providerOverride = provider ? settings?.providerOverrides?.[provider] || {} : {};
|
||||
const comboConfig = combo?.config || {};
|
||||
|
||||
// Clean undefined values before spreading
|
||||
const clean = (obj) =>
|
||||
Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined && v !== null));
|
||||
|
||||
return {
|
||||
...DEFAULT_COMBO_CONFIG,
|
||||
...clean(global),
|
||||
...clean(providerOverride),
|
||||
...clean(comboConfig),
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the default combo config (used when no overrides exist)
|
||||
*/
|
||||
export function getDefaultComboConfig() {
|
||||
return { ...DEFAULT_COMBO_CONFIG };
|
||||
}
|
||||
132
open-sse/services/comboMetrics.ts
Normal file
132
open-sse/services/comboMetrics.ts
Normal file
@@ -0,0 +1,132 @@
|
||||
/**
|
||||
* In-memory combo metrics tracker
|
||||
* Tracks per-combo and per-model request counts, latency, success/failure rates
|
||||
* Provides API for reading metrics from the dashboard
|
||||
*/
|
||||
|
||||
// In-memory store
|
||||
const metrics = new Map();
|
||||
|
||||
/**
|
||||
* Record a combo request result
|
||||
* @param {string} comboName
|
||||
* @param {string} modelStr - The model that handled the request (or null if all failed)
|
||||
* @param {Object} options
|
||||
* @param {boolean} options.success
|
||||
* @param {number} options.latencyMs
|
||||
* @param {number} options.fallbackCount - How many fallbacks occurred
|
||||
* @param {string} [options.strategy] - "priority" or "weighted"
|
||||
*/
|
||||
export function recordComboRequest(
|
||||
comboName,
|
||||
modelStr,
|
||||
{ success, latencyMs, fallbackCount = 0, strategy = "priority" }
|
||||
) {
|
||||
if (!metrics.has(comboName)) {
|
||||
metrics.set(comboName, {
|
||||
totalRequests: 0,
|
||||
totalSuccesses: 0,
|
||||
totalFailures: 0,
|
||||
totalFallbacks: 0,
|
||||
totalLatencyMs: 0,
|
||||
strategy,
|
||||
lastUsedAt: null,
|
||||
byModel: {},
|
||||
});
|
||||
}
|
||||
|
||||
const combo: any = metrics.get(comboName);
|
||||
combo.totalRequests++;
|
||||
combo.totalLatencyMs += latencyMs;
|
||||
combo.totalFallbacks += fallbackCount;
|
||||
combo.lastUsedAt = new Date().toISOString();
|
||||
combo.strategy = strategy;
|
||||
|
||||
if (success) {
|
||||
combo.totalSuccesses++;
|
||||
} else {
|
||||
combo.totalFailures++;
|
||||
}
|
||||
|
||||
// Per-model tracking
|
||||
if (modelStr) {
|
||||
if (!combo.byModel[modelStr]) {
|
||||
combo.byModel[modelStr] = {
|
||||
requests: 0,
|
||||
successes: 0,
|
||||
failures: 0,
|
||||
totalLatencyMs: 0,
|
||||
lastStatus: null,
|
||||
lastUsedAt: null,
|
||||
};
|
||||
}
|
||||
const modelMetric = combo.byModel[modelStr];
|
||||
modelMetric.requests++;
|
||||
modelMetric.totalLatencyMs += latencyMs;
|
||||
modelMetric.lastUsedAt = new Date().toISOString();
|
||||
|
||||
if (success) {
|
||||
modelMetric.successes++;
|
||||
modelMetric.lastStatus = "ok";
|
||||
} else {
|
||||
modelMetric.failures++;
|
||||
modelMetric.lastStatus = "error";
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Get metrics for a specific combo
|
||||
* @param {string} comboName
|
||||
* @returns {Object|null}
|
||||
*/
|
||||
export function getComboMetrics(comboName) {
|
||||
const combo: any = metrics.get(comboName);
|
||||
if (!combo) return null;
|
||||
|
||||
return {
|
||||
...combo,
|
||||
avgLatencyMs:
|
||||
combo.totalRequests > 0 ? Math.round(combo.totalLatencyMs / combo.totalRequests) : 0,
|
||||
successRate:
|
||||
combo.totalRequests > 0 ? Math.round((combo.totalSuccesses / combo.totalRequests) * 100) : 0,
|
||||
fallbackRate:
|
||||
combo.totalRequests > 0 ? Math.round((combo.totalFallbacks / combo.totalRequests) * 100) : 0,
|
||||
byModel: Object.fromEntries(
|
||||
Object.entries(combo.byModel).map(([model, m]: [string, any]) => [
|
||||
model,
|
||||
{
|
||||
...m,
|
||||
avgLatencyMs: m.requests > 0 ? Math.round(m.totalLatencyMs / m.requests) : 0,
|
||||
successRate: m.requests > 0 ? Math.round((m.successes / m.requests) * 100) : 0,
|
||||
},
|
||||
])
|
||||
),
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Get metrics for all combos
|
||||
* @returns {Object} Map of comboName → metrics
|
||||
*/
|
||||
export function getAllComboMetrics() {
|
||||
const result: Record<string, any> = {};
|
||||
for (const [name] of metrics) {
|
||||
result[name] = getComboMetrics(name);
|
||||
}
|
||||
return result;
|
||||
}
|
||||
|
||||
/**
|
||||
* Reset metrics for a specific combo
|
||||
*/
|
||||
export function resetComboMetrics(comboName) {
|
||||
metrics.delete(comboName);
|
||||
}
|
||||
|
||||
/**
|
||||
* Reset all combo metrics
|
||||
*/
|
||||
export function resetAllComboMetrics() {
|
||||
metrics.clear();
|
||||
}
|
||||
203
open-sse/services/contextManager.ts
Normal file
203
open-sse/services/contextManager.ts
Normal file
@@ -0,0 +1,203 @@
|
||||
/**
|
||||
* Context Manager — Phase 4
|
||||
*
|
||||
* Pre-flight context compression to prevent "prompt too long" errors.
|
||||
* 3 layers: trim tool messages, compress thinking, aggressive purification.
|
||||
*/
|
||||
|
||||
// Default token limits per provider (rough estimates based on model context windows)
|
||||
const DEFAULT_LIMITS = {
|
||||
claude: 200000,
|
||||
openai: 128000,
|
||||
gemini: 1000000,
|
||||
default: 128000,
|
||||
};
|
||||
|
||||
// Rough chars-per-token ratio for quick estimation
|
||||
const CHARS_PER_TOKEN = 4;
|
||||
|
||||
/**
|
||||
* Estimate token count from text length
|
||||
*/
|
||||
export function estimateTokens(text) {
|
||||
if (!text) return 0;
|
||||
const str = typeof text === "string" ? text : JSON.stringify(text);
|
||||
return Math.ceil(str.length / CHARS_PER_TOKEN);
|
||||
}
|
||||
|
||||
/**
|
||||
* Get token limit for a provider/model combination
|
||||
*/
|
||||
export function getTokenLimit(provider, model = null) {
|
||||
// Check if model has a known limit
|
||||
if (model) {
|
||||
const lower = model.toLowerCase();
|
||||
if (lower.includes("claude")) return DEFAULT_LIMITS.claude;
|
||||
if (lower.includes("gemini")) return DEFAULT_LIMITS.gemini;
|
||||
if (lower.includes("gpt") || lower.includes("o1") || lower.includes("o3") || lower.includes("o4")) return DEFAULT_LIMITS.openai;
|
||||
}
|
||||
return DEFAULT_LIMITS[provider] || DEFAULT_LIMITS.default;
|
||||
}
|
||||
|
||||
/**
|
||||
* Apply context compression to request body.
|
||||
* Operates in 3 layers of increasing aggressiveness:
|
||||
*
|
||||
* Layer 1: Trim tool_result messages (truncate long outputs)
|
||||
* Layer 2: Compress thinking blocks (remove from history, keep last)
|
||||
* Layer 3: Aggressive purification (drop old messages until fitting)
|
||||
*
|
||||
* @param {object} body - Request body with messages[]
|
||||
* @param {object} options - { provider?, model?, maxTokens?, reserveTokens? }
|
||||
* @returns {{ body: object, compressed: boolean, stats: object }}
|
||||
*/
|
||||
export function compressContext(body, options: any = {}) {
|
||||
if (!body || !body.messages || !Array.isArray(body.messages)) {
|
||||
return { body, compressed: false, stats: {} };
|
||||
}
|
||||
|
||||
const provider = options.provider || "default";
|
||||
const maxTokens = options.maxTokens || getTokenLimit(provider, body.model || options.model);
|
||||
const reserveTokens = options.reserveTokens || 16000; // Reserve for response
|
||||
const targetTokens = maxTokens - reserveTokens;
|
||||
|
||||
let messages = [...body.messages];
|
||||
let currentTokens = estimateTokens(JSON.stringify(messages));
|
||||
const stats = { original: currentTokens, layers: [] };
|
||||
|
||||
// Already fits
|
||||
if (currentTokens <= targetTokens) {
|
||||
return { body, compressed: false, stats: { original: currentTokens, final: currentTokens } };
|
||||
}
|
||||
|
||||
// Layer 1: Trim tool_result/tool messages
|
||||
messages = trimToolMessages(messages, 2000); // Max 2000 chars per tool result
|
||||
currentTokens = estimateTokens(JSON.stringify(messages));
|
||||
stats.layers.push({ name: "trim_tools", tokens: currentTokens });
|
||||
|
||||
if (currentTokens <= targetTokens) {
|
||||
return {
|
||||
body: { ...body, messages },
|
||||
compressed: true,
|
||||
stats: { ...stats, final: currentTokens },
|
||||
};
|
||||
}
|
||||
|
||||
// Layer 2: Compress thinking blocks (remove from non-last assistant messages)
|
||||
messages = compressThinking(messages);
|
||||
currentTokens = estimateTokens(JSON.stringify(messages));
|
||||
stats.layers.push({ name: "compress_thinking", tokens: currentTokens });
|
||||
|
||||
if (currentTokens <= targetTokens) {
|
||||
return {
|
||||
body: { ...body, messages },
|
||||
compressed: true,
|
||||
stats: { ...stats, final: currentTokens },
|
||||
};
|
||||
}
|
||||
|
||||
// Layer 3: Aggressive purification — drop oldest messages keeping system + last N pairs
|
||||
messages = purifyHistory(messages, targetTokens);
|
||||
currentTokens = estimateTokens(JSON.stringify(messages));
|
||||
stats.layers.push({ name: "purify_history", tokens: currentTokens });
|
||||
|
||||
return {
|
||||
body: { ...body, messages },
|
||||
compressed: true,
|
||||
stats: { ...stats, final: currentTokens },
|
||||
};
|
||||
}
|
||||
|
||||
// ─── Layer 1: Trim Tool Messages ────────────────────────────────────────────
|
||||
|
||||
function trimToolMessages(messages, maxChars) {
|
||||
return messages.map((msg) => {
|
||||
if (msg.role === "tool" && typeof msg.content === "string" && msg.content.length > maxChars) {
|
||||
return {
|
||||
...msg,
|
||||
content: msg.content.slice(0, maxChars) + "\n... [truncated]",
|
||||
};
|
||||
}
|
||||
// Handle array content (Claude format with tool_result blocks)
|
||||
if (msg.role === "user" && Array.isArray(msg.content)) {
|
||||
return {
|
||||
...msg,
|
||||
content: msg.content.map((block) => {
|
||||
if (block.type === "tool_result" && typeof block.content === "string" && block.content.length > maxChars) {
|
||||
return { ...block, content: block.content.slice(0, maxChars) + "\n... [truncated]" };
|
||||
}
|
||||
return block;
|
||||
}),
|
||||
};
|
||||
}
|
||||
return msg;
|
||||
});
|
||||
}
|
||||
|
||||
// ─── Layer 2: Compress Thinking Blocks ──────────────────────────────────────
|
||||
|
||||
function compressThinking(messages) {
|
||||
// Find last assistant message index
|
||||
let lastAssistantIdx = -1;
|
||||
for (let i = messages.length - 1; i >= 0; i--) {
|
||||
if (messages[i].role === "assistant") {
|
||||
lastAssistantIdx = i;
|
||||
break;
|
||||
}
|
||||
}
|
||||
|
||||
return messages.map((msg, i) => {
|
||||
if (msg.role !== "assistant") return msg;
|
||||
if (i === lastAssistantIdx) return msg; // Keep thinking in last assistant msg
|
||||
|
||||
// Remove thinking blocks from content array
|
||||
if (Array.isArray(msg.content)) {
|
||||
const filtered = msg.content.filter((block) => block.type !== "thinking");
|
||||
if (filtered.length === 0) {
|
||||
return { ...msg, content: "[thinking compressed]" };
|
||||
}
|
||||
return { ...msg, content: filtered };
|
||||
}
|
||||
|
||||
// Remove thinking XML tags from string content
|
||||
if (typeof msg.content === "string") {
|
||||
const cleaned = msg.content
|
||||
.replace(/<thinking>[\s\S]*?<\/thinking>/g, "")
|
||||
.replace(/<antThinking>[\s\S]*?<\/antThinking>/g, "")
|
||||
.trim();
|
||||
return { ...msg, content: cleaned || "[thinking compressed]" };
|
||||
}
|
||||
|
||||
return msg;
|
||||
});
|
||||
}
|
||||
|
||||
// ─── Layer 3: Aggressive Purification ───────────────────────────────────────
|
||||
|
||||
function purifyHistory(messages, targetTokens) {
|
||||
// Keep system message(s) and the last N message pairs
|
||||
const system = messages.filter((m) => m.role === "system" || m.role === "developer");
|
||||
const nonSystem = messages.filter((m) => m.role !== "system" && m.role !== "developer");
|
||||
|
||||
// Binary search for how many messages to keep from the end
|
||||
let keep = nonSystem.length;
|
||||
while (keep > 2) {
|
||||
const candidate = [...system, ...nonSystem.slice(-keep)];
|
||||
const tokens = estimateTokens(JSON.stringify(candidate));
|
||||
if (tokens <= targetTokens) break;
|
||||
keep = Math.max(2, Math.floor(keep * 0.7)); // Drop 30% each iteration
|
||||
}
|
||||
|
||||
const result = [...system, ...nonSystem.slice(-keep)];
|
||||
|
||||
// Add summary of dropped messages
|
||||
if (keep < nonSystem.length) {
|
||||
const dropped = nonSystem.length - keep;
|
||||
result.splice(system.length, 0, {
|
||||
role: "system",
|
||||
content: `[Context compressed: ${dropped} earlier messages removed to fit context window]`,
|
||||
});
|
||||
}
|
||||
|
||||
return result;
|
||||
}
|
||||
249
open-sse/services/ipFilter.ts
Normal file
249
open-sse/services/ipFilter.ts
Normal file
@@ -0,0 +1,249 @@
|
||||
/**
|
||||
* IP Filter Middleware — Phase 6
|
||||
*
|
||||
* IP-based access control with blacklist, whitelist, priority modes, and temporary bans.
|
||||
*/
|
||||
|
||||
// In-memory IP lists
|
||||
let _config = {
|
||||
enabled: false,
|
||||
mode: "blacklist", // "blacklist" | "whitelist" | "whitelist-priority"
|
||||
blacklist: new Set(),
|
||||
whitelist: new Set(),
|
||||
tempBans: new Map(), // IP → { until: timestamp, reason: string }
|
||||
};
|
||||
|
||||
/**
|
||||
* Configure the IP filter
|
||||
*/
|
||||
export function configureIPFilter(config) {
|
||||
if (config.enabled !== undefined) _config.enabled = config.enabled;
|
||||
if (config.mode) _config.mode = config.mode;
|
||||
if (config.blacklist) _config.blacklist = new Set(config.blacklist);
|
||||
if (config.whitelist) _config.whitelist = new Set(config.whitelist);
|
||||
}
|
||||
|
||||
/**
|
||||
* Get current IP filter config (for API)
|
||||
*/
|
||||
export function getIPFilterConfig() {
|
||||
return {
|
||||
enabled: _config.enabled,
|
||||
mode: _config.mode,
|
||||
blacklist: Array.from(_config.blacklist),
|
||||
whitelist: Array.from(_config.whitelist),
|
||||
tempBans: Array.from(_config.tempBans.entries()).map(([ip, info]) => ({
|
||||
ip,
|
||||
until: new Date(info.until).toISOString(),
|
||||
reason: info.reason,
|
||||
remainingMs: Math.max(0, info.until - Date.now()),
|
||||
})),
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if an IP is allowed
|
||||
* @param {string} ip
|
||||
* @returns {{ allowed: boolean, reason?: string }}
|
||||
*/
|
||||
export function checkIP(ip) {
|
||||
if (!_config.enabled) return { allowed: true };
|
||||
if (!ip) return { allowed: true };
|
||||
|
||||
const normalizedIP = normalizeIP(ip);
|
||||
|
||||
// Check temp bans first (highest priority)
|
||||
const ban = _config.tempBans.get(normalizedIP);
|
||||
if (ban) {
|
||||
if (Date.now() < ban.until) {
|
||||
return { allowed: false, reason: `Temporarily banned: ${ban.reason}` };
|
||||
}
|
||||
_config.tempBans.delete(normalizedIP); // Expired
|
||||
}
|
||||
|
||||
switch (_config.mode) {
|
||||
case "whitelist":
|
||||
// Only whitelisted IPs allowed
|
||||
if (!matchesAny(normalizedIP, _config.whitelist)) {
|
||||
return { allowed: false, reason: "IP not in whitelist" };
|
||||
}
|
||||
return { allowed: true };
|
||||
|
||||
case "whitelist-priority":
|
||||
// Whitelist overrides blacklist
|
||||
if (matchesAny(normalizedIP, _config.whitelist)) {
|
||||
return { allowed: true };
|
||||
}
|
||||
if (matchesAny(normalizedIP, _config.blacklist)) {
|
||||
return { allowed: false, reason: "IP blacklisted" };
|
||||
}
|
||||
return { allowed: true };
|
||||
|
||||
case "blacklist":
|
||||
default:
|
||||
// Blacklisted IPs blocked
|
||||
if (matchesAny(normalizedIP, _config.blacklist)) {
|
||||
return { allowed: false, reason: "IP blacklisted" };
|
||||
}
|
||||
return { allowed: true };
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Temporarily ban an IP
|
||||
*/
|
||||
export function tempBanIP(ip, durationMs, reason = "Automated ban") {
|
||||
const normalizedIP = normalizeIP(ip);
|
||||
_config.tempBans.set(normalizedIP, {
|
||||
until: Date.now() + durationMs,
|
||||
reason,
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Remove a temporary ban
|
||||
*/
|
||||
export function removeTempBan(ip) {
|
||||
_config.tempBans.delete(normalizeIP(ip));
|
||||
}
|
||||
|
||||
/**
|
||||
* Add IP to blacklist
|
||||
*/
|
||||
export function addToBlacklist(ip) {
|
||||
_config.blacklist.add(normalizeIP(ip));
|
||||
}
|
||||
|
||||
/**
|
||||
* Remove IP from blacklist
|
||||
*/
|
||||
export function removeFromBlacklist(ip) {
|
||||
_config.blacklist.delete(normalizeIP(ip));
|
||||
}
|
||||
|
||||
/**
|
||||
* Add IP to whitelist
|
||||
*/
|
||||
export function addToWhitelist(ip) {
|
||||
_config.whitelist.add(normalizeIP(ip));
|
||||
}
|
||||
|
||||
/**
|
||||
* Remove IP from whitelist
|
||||
*/
|
||||
export function removeFromWhitelist(ip) {
|
||||
_config.whitelist.delete(normalizeIP(ip));
|
||||
}
|
||||
|
||||
/**
|
||||
* Express/Next.js middleware factory
|
||||
*/
|
||||
export function createIPFilterMiddleware() {
|
||||
return (req, res, next) => {
|
||||
const ip = extractClientIP(req);
|
||||
const { allowed, reason } = checkIP(ip);
|
||||
if (!allowed) {
|
||||
const statusCode = 403;
|
||||
if (res.status) {
|
||||
// Express
|
||||
return res.status(statusCode).json({ error: reason || "Access denied" });
|
||||
}
|
||||
// Raw response
|
||||
res.writeHead(statusCode, { "Content-Type": "application/json" });
|
||||
return res.end(JSON.stringify({ error: reason || "Access denied" }));
|
||||
}
|
||||
if (next) next();
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* For Next.js App Router — check IP from request object
|
||||
*/
|
||||
export function checkRequestIP(request) {
|
||||
const ip =
|
||||
request.headers?.get?.("x-forwarded-for")?.split(",")[0].trim() ||
|
||||
request.headers?.get?.("x-real-ip") ||
|
||||
request.headers?.get?.("cf-connecting-ip") ||
|
||||
request.ip ||
|
||||
"unknown";
|
||||
return checkIP(ip);
|
||||
}
|
||||
|
||||
// ─── Internal Helpers ───────────────────────────────────────────────────────
|
||||
|
||||
function normalizeIP(ip) {
|
||||
if (!ip) return "";
|
||||
// Remove IPv6 prefix from IPv4-mapped addresses
|
||||
return ip.replace(/^::ffff:/, "").trim();
|
||||
}
|
||||
|
||||
function matchesAny(ip, ipSet) {
|
||||
// Direct match
|
||||
if (ipSet.has(ip)) return true;
|
||||
|
||||
// CIDR match
|
||||
for (const entry of ipSet) {
|
||||
if (entry.includes("/") && matchesCIDR(ip, entry)) return true;
|
||||
// Wildcard match (e.g., "192.168.*.*")
|
||||
if (entry.includes("*") && matchesWildcard(ip, entry)) return true;
|
||||
}
|
||||
return false;
|
||||
}
|
||||
|
||||
function matchesCIDR(ip, cidr) {
|
||||
try {
|
||||
const [range, bits] = cidr.split("/");
|
||||
const mask = parseInt(bits, 10);
|
||||
if (isNaN(mask) || mask < 0 || mask > 32) return false;
|
||||
const ipNum = ipToNum(ip);
|
||||
const rangeNum = ipToNum(range);
|
||||
if (ipNum === null || rangeNum === null) return false;
|
||||
const maskBits = (-1 << (32 - mask)) >>> 0;
|
||||
return (ipNum & maskBits) === (rangeNum & maskBits);
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
function ipToNum(ip) {
|
||||
const parts = ip.split(".");
|
||||
if (parts.length !== 4) return null;
|
||||
let num = 0;
|
||||
for (const p of parts) {
|
||||
const n = parseInt(p, 10);
|
||||
if (isNaN(n) || n < 0 || n > 255) return null;
|
||||
num = (num << 8) | n;
|
||||
}
|
||||
return num >>> 0;
|
||||
}
|
||||
|
||||
function matchesWildcard(ip, pattern) {
|
||||
const ipParts = ip.split(".");
|
||||
const patParts = pattern.split(".");
|
||||
if (ipParts.length !== 4 || patParts.length !== 4) return false;
|
||||
return ipParts.every((part, i) => patParts[i] === "*" || part === patParts[i]);
|
||||
}
|
||||
|
||||
function extractClientIP(req) {
|
||||
return (
|
||||
req.headers?.["x-forwarded-for"]?.split(",")[0].trim() ||
|
||||
req.headers?.["x-real-ip"] ||
|
||||
req.headers?.["cf-connecting-ip"] ||
|
||||
req.socket?.remoteAddress ||
|
||||
req.ip ||
|
||||
"unknown"
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Reset config (for testing)
|
||||
*/
|
||||
export function resetIPFilter() {
|
||||
_config = {
|
||||
enabled: false,
|
||||
mode: "blacklist",
|
||||
blacklist: new Set(),
|
||||
whitelist: new Set(),
|
||||
tempBans: new Map(),
|
||||
};
|
||||
}
|
||||
188
open-sse/services/model.ts
Normal file
188
open-sse/services/model.ts
Normal file
@@ -0,0 +1,188 @@
|
||||
import { PROVIDER_ID_TO_ALIAS, PROVIDER_MODELS } from "../config/providerModels.ts";
|
||||
|
||||
// Derive alias→provider mapping from the single source of truth (PROVIDER_ID_TO_ALIAS)
|
||||
// This prevents the two maps from drifting out of sync
|
||||
const ALIAS_TO_PROVIDER_ID = {};
|
||||
for (const [id, alias] of Object.entries(PROVIDER_ID_TO_ALIAS)) {
|
||||
if (ALIAS_TO_PROVIDER_ID[alias]) {
|
||||
console.log(
|
||||
`[MODEL] Warning: alias "${alias}" maps to both "${ALIAS_TO_PROVIDER_ID[alias]}" and "${id}". Using "${id}".`
|
||||
);
|
||||
}
|
||||
ALIAS_TO_PROVIDER_ID[alias] = id;
|
||||
}
|
||||
|
||||
// Provider-scoped legacy model aliases. Used to normalize provider/model inputs
|
||||
// and keep backward compatibility when upstream IDs change.
|
||||
const PROVIDER_MODEL_ALIASES = {
|
||||
github: {
|
||||
"claude-4.5-opus": "claude-opus-4-5-20251101",
|
||||
"claude-opus-4.5": "claude-opus-4-5-20251101",
|
||||
"gemini-3-pro": "gemini-3-pro-preview",
|
||||
"gemini-3-flash": "gemini-3-flash-preview",
|
||||
"raptor-mini": "oswe-vscode-prime",
|
||||
},
|
||||
antigravity: {
|
||||
"gemini-3-flash": "gemini-3-flash-preview",
|
||||
},
|
||||
};
|
||||
|
||||
// Reverse index: modelId -> providerIds that expose this model
|
||||
const MODEL_TO_PROVIDERS = new Map();
|
||||
for (const [aliasOrId, models] of Object.entries(PROVIDER_MODELS)) {
|
||||
const providerId = ALIAS_TO_PROVIDER_ID[aliasOrId] || aliasOrId;
|
||||
for (const modelEntry of models || []) {
|
||||
const modelId = modelEntry?.id;
|
||||
if (!modelId) continue;
|
||||
const providers = MODEL_TO_PROVIDERS.get(modelId) || [];
|
||||
if (!providers.includes(providerId)) {
|
||||
providers.push(providerId);
|
||||
MODEL_TO_PROVIDERS.set(modelId, providers);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Resolve provider alias to provider ID
|
||||
*/
|
||||
export function resolveProviderAlias(aliasOrId) {
|
||||
return ALIAS_TO_PROVIDER_ID[aliasOrId] || aliasOrId;
|
||||
}
|
||||
|
||||
/**
|
||||
* Resolve provider-specific legacy model alias to canonical model ID.
|
||||
*/
|
||||
function resolveProviderModelAlias(providerOrAlias, modelId) {
|
||||
if (!modelId || typeof modelId !== "string") return modelId;
|
||||
const providerId = resolveProviderAlias(providerOrAlias);
|
||||
const aliases = PROVIDER_MODEL_ALIASES[providerId];
|
||||
return aliases?.[modelId] || modelId;
|
||||
}
|
||||
|
||||
/**
|
||||
* Parse model string: "alias/model" or "provider/model" or just alias
|
||||
*/
|
||||
export function parseModel(modelStr) {
|
||||
if (!modelStr) {
|
||||
return { provider: null, model: null, isAlias: false, providerAlias: null };
|
||||
}
|
||||
|
||||
// Sanitize: reject strings with path traversal or control characters
|
||||
if (/\.\.[\/\\]/.test(modelStr) || /[\x00-\x1f]/.test(modelStr)) {
|
||||
console.log(`[MODEL] Warning: rejected malformed model string: "${modelStr.substring(0, 50)}"`);
|
||||
return { provider: null, model: null, isAlias: false, providerAlias: null };
|
||||
}
|
||||
|
||||
// Check if standard format: provider/model or alias/model
|
||||
if (modelStr.includes("/")) {
|
||||
const firstSlash = modelStr.indexOf("/");
|
||||
const providerOrAlias = modelStr.slice(0, firstSlash);
|
||||
const model = modelStr.slice(firstSlash + 1);
|
||||
const provider = resolveProviderAlias(providerOrAlias);
|
||||
return { provider, model, isAlias: false, providerAlias: providerOrAlias };
|
||||
}
|
||||
|
||||
// Alias format (model alias, not provider alias)
|
||||
return { provider: null, model: modelStr, isAlias: true, providerAlias: null };
|
||||
}
|
||||
|
||||
/**
|
||||
* Resolve model alias from aliases object
|
||||
* Format: { "alias": "provider/model" }
|
||||
*/
|
||||
export function resolveModelAliasFromMap(alias, aliases) {
|
||||
if (!aliases) return null;
|
||||
|
||||
// Check if alias exists
|
||||
const resolved = aliases[alias];
|
||||
if (!resolved) return null;
|
||||
|
||||
// Resolved value is "provider/model" format
|
||||
if (typeof resolved === "string" && resolved.includes("/")) {
|
||||
const firstSlash = resolved.indexOf("/");
|
||||
const providerOrAlias = resolved.slice(0, firstSlash);
|
||||
return {
|
||||
provider: resolveProviderAlias(providerOrAlias),
|
||||
model: resolved.slice(firstSlash + 1),
|
||||
};
|
||||
}
|
||||
|
||||
// Or object { provider, model }
|
||||
if (typeof resolved === "object" && resolved.provider && resolved.model) {
|
||||
return {
|
||||
provider: resolveProviderAlias(resolved.provider),
|
||||
model: resolved.model,
|
||||
};
|
||||
}
|
||||
|
||||
return null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get full model info (parse or resolve)
|
||||
* @param {string} modelStr - Model string
|
||||
* @param {object|function} aliasesOrGetter - Aliases object or async function to get aliases
|
||||
*/
|
||||
export async function getModelInfoCore(modelStr, aliasesOrGetter) {
|
||||
const parsed = parseModel(modelStr);
|
||||
|
||||
if (!parsed.isAlias) {
|
||||
const canonicalModel = resolveProviderModelAlias(parsed.provider, parsed.model);
|
||||
return {
|
||||
provider: parsed.provider,
|
||||
model: canonicalModel,
|
||||
};
|
||||
}
|
||||
|
||||
// Get aliases (from object or function)
|
||||
const aliases = typeof aliasesOrGetter === "function" ? await aliasesOrGetter() : aliasesOrGetter;
|
||||
|
||||
// Resolve alias
|
||||
const resolved = resolveModelAliasFromMap(parsed.model, aliases);
|
||||
if (resolved) {
|
||||
const canonicalModel = resolveProviderModelAlias(resolved.provider, resolved.model);
|
||||
return {
|
||||
provider: resolved.provider,
|
||||
model: canonicalModel,
|
||||
};
|
||||
}
|
||||
|
||||
const modelId = parsed.model;
|
||||
const providers = MODEL_TO_PROVIDERS.get(modelId) || [];
|
||||
|
||||
// Preserve historical behavior: OpenAI stays default when model exists there
|
||||
if (providers.includes("openai")) {
|
||||
return {
|
||||
provider: "openai",
|
||||
model: modelId,
|
||||
};
|
||||
}
|
||||
|
||||
const nonOpenAIProviders = providers.filter((p) => p !== "openai");
|
||||
if (nonOpenAIProviders.length === 1) {
|
||||
const provider = nonOpenAIProviders[0];
|
||||
const canonicalModel = resolveProviderModelAlias(provider, modelId);
|
||||
return { provider, model: canonicalModel };
|
||||
}
|
||||
|
||||
if (nonOpenAIProviders.length > 1) {
|
||||
const aliasesForHint = nonOpenAIProviders.map((p) => PROVIDER_ID_TO_ALIAS[p] || p);
|
||||
const hints = aliasesForHint.slice(0, 2).map((alias) => `${alias}/${modelId}`);
|
||||
const message = `Ambiguous model '${modelId}'. Use provider/model prefix (ex: ${hints.join(" or ")}).`;
|
||||
console.warn(`[MODEL] ${message} Candidates: ${aliasesForHint.join(", ")}`);
|
||||
return {
|
||||
provider: null,
|
||||
model: modelId,
|
||||
errorType: "ambiguous_model",
|
||||
errorMessage: message,
|
||||
candidateProviders: nonOpenAIProviders,
|
||||
candidateAliases: aliasesForHint,
|
||||
};
|
||||
}
|
||||
|
||||
// Fallback: treat as openai model
|
||||
return {
|
||||
provider: "openai",
|
||||
model: modelId,
|
||||
};
|
||||
}
|
||||
297
open-sse/services/provider.ts
Normal file
297
open-sse/services/provider.ts
Normal file
@@ -0,0 +1,297 @@
|
||||
import { PROVIDERS } from "../config/constants.ts";
|
||||
import { getRegistryEntry } from "../config/providerRegistry.ts";
|
||||
|
||||
const OPENAI_COMPATIBLE_PREFIX = "openai-compatible-";
|
||||
const OPENAI_COMPATIBLE_DEFAULTS = {
|
||||
baseUrl: "https://api.openai.com/v1",
|
||||
};
|
||||
|
||||
const ANTHROPIC_COMPATIBLE_PREFIX = "anthropic-compatible-";
|
||||
const ANTHROPIC_COMPATIBLE_DEFAULTS = {
|
||||
baseUrl: "https://api.anthropic.com/v1",
|
||||
};
|
||||
|
||||
function isOpenAICompatible(provider) {
|
||||
return typeof provider === "string" && provider.startsWith(OPENAI_COMPATIBLE_PREFIX);
|
||||
}
|
||||
|
||||
function isAnthropicCompatible(provider) {
|
||||
return typeof provider === "string" && provider.startsWith(ANTHROPIC_COMPATIBLE_PREFIX);
|
||||
}
|
||||
|
||||
function getOpenAICompatibleType(provider) {
|
||||
if (!isOpenAICompatible(provider)) return "chat";
|
||||
return provider.includes("responses") ? "responses" : "chat";
|
||||
}
|
||||
|
||||
function buildOpenAICompatibleUrl(baseUrl, apiType) {
|
||||
const normalized = baseUrl.replace(/\/$/, "");
|
||||
const path = apiType === "responses" ? "/responses" : "/chat/completions";
|
||||
return `${normalized}${path}`;
|
||||
}
|
||||
|
||||
function buildAnthropicCompatibleUrl(baseUrl) {
|
||||
const normalized = baseUrl.replace(/\/$/, "");
|
||||
return `${normalized}/messages`;
|
||||
}
|
||||
|
||||
// Detect request format from body structure
|
||||
export function detectFormat(body) {
|
||||
// OpenAI Responses API:
|
||||
// - input can be string, array, or object (not only array)
|
||||
// - some clients send responses-specific fields even when input is omitted
|
||||
const hasInputField =
|
||||
Object.prototype.hasOwnProperty.call(body, "input") && body.input !== undefined;
|
||||
const hasResponsesSpecificFields =
|
||||
body.max_output_tokens !== undefined ||
|
||||
body.previous_response_id !== undefined ||
|
||||
body.reasoning !== undefined;
|
||||
if (hasInputField || hasResponsesSpecificFields) {
|
||||
return "openai-responses";
|
||||
}
|
||||
|
||||
// Antigravity format: Gemini wrapped in body.request
|
||||
if (body.request?.contents && body.userAgent === "antigravity") {
|
||||
return "antigravity";
|
||||
}
|
||||
|
||||
// Gemini format: has contents array
|
||||
if (body.contents && Array.isArray(body.contents)) {
|
||||
return "gemini";
|
||||
}
|
||||
|
||||
// OpenAI-specific indicators (check BEFORE Claude)
|
||||
// These fields are OpenAI-specific and never appear in Claude format
|
||||
if (
|
||||
body.stream_options || // OpenAI streaming options
|
||||
body.response_format || // JSON mode, etc.
|
||||
body.logprobs !== undefined || // Log probabilities
|
||||
body.top_logprobs !== undefined ||
|
||||
body.n !== undefined || // Number of completions
|
||||
body.presence_penalty !== undefined || // Penalties
|
||||
body.frequency_penalty !== undefined ||
|
||||
body.logit_bias || // Token biasing
|
||||
body.user // User identifier
|
||||
) {
|
||||
return "openai";
|
||||
}
|
||||
|
||||
// Claude format: messages with content as array of objects with type
|
||||
// Claude requires content to be array with specific structure
|
||||
if (body.messages && Array.isArray(body.messages)) {
|
||||
const firstMsg = body.messages[0];
|
||||
|
||||
// If content is array, check if it follows Claude structure
|
||||
if (firstMsg?.content && Array.isArray(firstMsg.content)) {
|
||||
const firstContent = firstMsg.content[0];
|
||||
|
||||
// Claude format has specific types: text, image, tool_use, tool_result
|
||||
// OpenAI multimodal has: text, image_url (note the difference)
|
||||
if (firstContent?.type === "text" && !body.model?.includes("/")) {
|
||||
// Could be Claude or OpenAI multimodal
|
||||
// Check for Claude-specific fields
|
||||
if (body.system || body.anthropic_version) {
|
||||
return "claude";
|
||||
}
|
||||
// Check if image format is Claude (source.type) vs OpenAI (image_url.url)
|
||||
const hasClaudeImage = firstMsg.content.some(
|
||||
(c) => c.type === "image" && c.source?.type === "base64"
|
||||
);
|
||||
const hasOpenAIImage = firstMsg.content.some(
|
||||
(c) => c.type === "image_url" && c.image_url?.url
|
||||
);
|
||||
if (hasClaudeImage) return "claude";
|
||||
if (hasOpenAIImage) return "openai";
|
||||
|
||||
// If still unclear, check for tool format
|
||||
const hasClaudeTool = firstMsg.content.some(
|
||||
(c) => c.type === "tool_use" || c.type === "tool_result"
|
||||
);
|
||||
if (hasClaudeTool) return "claude";
|
||||
}
|
||||
}
|
||||
|
||||
// If content is string, it's likely OpenAI (Claude also supports this)
|
||||
// Check for other Claude-specific indicators
|
||||
if (body.system !== undefined || body.anthropic_version) {
|
||||
return "claude";
|
||||
}
|
||||
|
||||
// Additional Claude heuristic: max_tokens is a required Claude field
|
||||
// and Claude requests rarely include OpenAI-specific fields like
|
||||
// stream_options, response_format, or logprobs
|
||||
if (body.max_tokens && !body.stream_options && !body.response_format) {
|
||||
return "claude";
|
||||
}
|
||||
}
|
||||
|
||||
// Default to OpenAI format
|
||||
return "openai";
|
||||
}
|
||||
|
||||
// Get provider config
|
||||
export function getProviderConfig(provider) {
|
||||
if (isOpenAICompatible(provider)) {
|
||||
const apiType = getOpenAICompatibleType(provider);
|
||||
return {
|
||||
...PROVIDERS.openai,
|
||||
format: apiType === "responses" ? "openai-responses" : "openai",
|
||||
baseUrl: OPENAI_COMPATIBLE_DEFAULTS.baseUrl,
|
||||
};
|
||||
}
|
||||
if (isAnthropicCompatible(provider)) {
|
||||
return {
|
||||
...PROVIDERS.anthropic, // Use Anthropic defaults (header: x-api-key)
|
||||
format: "claude",
|
||||
baseUrl: ANTHROPIC_COMPATIBLE_DEFAULTS.baseUrl,
|
||||
};
|
||||
}
|
||||
return PROVIDERS[provider] || PROVIDERS.openai;
|
||||
}
|
||||
|
||||
// Get number of fallback URLs for provider (for retry logic)
|
||||
export function getProviderFallbackCount(provider) {
|
||||
const config = getProviderConfig(provider);
|
||||
return config.baseUrls?.length || 1;
|
||||
}
|
||||
|
||||
// Build provider URL
|
||||
export function buildProviderUrl(provider, model, stream = true, options: any = {}) {
|
||||
if (isOpenAICompatible(provider)) {
|
||||
const apiType = getOpenAICompatibleType(provider);
|
||||
const baseUrl = options?.baseUrl || OPENAI_COMPATIBLE_DEFAULTS.baseUrl;
|
||||
return buildOpenAICompatibleUrl(baseUrl, apiType);
|
||||
}
|
||||
if (isAnthropicCompatible(provider)) {
|
||||
const baseUrl = options?.baseUrl || ANTHROPIC_COMPATIBLE_DEFAULTS.baseUrl;
|
||||
return buildAnthropicCompatibleUrl(baseUrl);
|
||||
}
|
||||
|
||||
const entry = getRegistryEntry(provider);
|
||||
const config = getProviderConfig(provider);
|
||||
|
||||
// Registry-driven URL building
|
||||
if (entry) {
|
||||
// Multi-URL providers (e.g. antigravity)
|
||||
if (entry.baseUrls) {
|
||||
const urlIndex = options?.baseUrlIndex || 0;
|
||||
const baseUrl = entry.baseUrls[urlIndex] || entry.baseUrls[0];
|
||||
if (entry.urlBuilder) return entry.urlBuilder(baseUrl, model, stream);
|
||||
return baseUrl;
|
||||
}
|
||||
// Custom URL builder (e.g. gemini, gemini-cli)
|
||||
if (entry.urlBuilder) {
|
||||
return entry.urlBuilder(entry.baseUrl, model, stream);
|
||||
}
|
||||
// URL suffix (e.g. claude: ?beta=true)
|
||||
if (entry.urlSuffix) {
|
||||
return `${entry.baseUrl}${entry.urlSuffix}`;
|
||||
}
|
||||
}
|
||||
|
||||
return config.baseUrl;
|
||||
}
|
||||
|
||||
// Build provider headers
|
||||
export function buildProviderHeaders(provider, credentials, stream = true, body = null) {
|
||||
const config = getProviderConfig(provider);
|
||||
const entry = getRegistryEntry(provider);
|
||||
const headers = {
|
||||
"Content-Type": "application/json",
|
||||
...config.headers,
|
||||
};
|
||||
|
||||
// Add auth header
|
||||
// Specific override for Anthropic Compatible
|
||||
if (isAnthropicCompatible(provider)) {
|
||||
if (credentials.apiKey) {
|
||||
headers["x-api-key"] = credentials.apiKey;
|
||||
} else if (credentials.accessToken) {
|
||||
headers["Authorization"] = `Bearer ${credentials.accessToken}`;
|
||||
}
|
||||
if (!headers["anthropic-version"]) {
|
||||
headers["anthropic-version"] = "2023-06-01";
|
||||
}
|
||||
} else if (provider === "github") {
|
||||
// GitHub Copilot requires special dynamic headers (x-request-id)
|
||||
const githubToken = credentials.copilotToken || credentials.accessToken;
|
||||
headers["Authorization"] = `Bearer ${githubToken}`;
|
||||
headers["x-request-id"] = crypto.randomUUID
|
||||
? crypto.randomUUID()
|
||||
: "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, function (c) {
|
||||
const r = (Math.random() * 16) | 0;
|
||||
const v = c == "x" ? r : (r & 0x3) | 0x8;
|
||||
return v.toString(16);
|
||||
});
|
||||
if (!stream) {
|
||||
headers["Accept"] = "application/json";
|
||||
}
|
||||
} else if (entry) {
|
||||
// Registry-driven auth
|
||||
const authHeader = entry.authHeader || "bearer";
|
||||
if (authHeader === "x-api-key") {
|
||||
const token = credentials.apiKey || credentials.accessToken;
|
||||
if (token) {
|
||||
headers["x-api-key"] = token;
|
||||
}
|
||||
} else if (authHeader === "x-goog-api-key") {
|
||||
if (credentials.apiKey) {
|
||||
headers["x-goog-api-key"] = credentials.apiKey;
|
||||
} else if (credentials.accessToken) {
|
||||
headers["Authorization"] = `Bearer ${credentials.accessToken}`;
|
||||
}
|
||||
} else {
|
||||
// bearer (default)
|
||||
headers["Authorization"] = `Bearer ${credentials.apiKey || credentials.accessToken}`;
|
||||
}
|
||||
} else {
|
||||
// Fallback for unknown providers
|
||||
headers["Authorization"] = `Bearer ${credentials.apiKey || credentials.accessToken}`;
|
||||
}
|
||||
|
||||
// Stream accept header
|
||||
if (stream) {
|
||||
headers["Accept"] = "text/event-stream";
|
||||
}
|
||||
|
||||
return headers;
|
||||
}
|
||||
|
||||
// Get target format for provider
|
||||
export function getTargetFormat(provider) {
|
||||
if (isOpenAICompatible(provider)) {
|
||||
return getOpenAICompatibleType(provider) === "responses" ? "openai-responses" : "openai";
|
||||
}
|
||||
if (isAnthropicCompatible(provider)) {
|
||||
return "claude";
|
||||
}
|
||||
// Registry-driven format lookup
|
||||
const entry = getRegistryEntry(provider);
|
||||
if (entry) return entry.format || "openai";
|
||||
const config = getProviderConfig(provider);
|
||||
return config.format || "openai";
|
||||
}
|
||||
|
||||
// Check if last message is from user
|
||||
export function isLastMessageFromUser(body) {
|
||||
const messages = body.messages || body.contents;
|
||||
if (!messages?.length) return true;
|
||||
const lastMsg = messages[messages.length - 1];
|
||||
return lastMsg?.role === "user";
|
||||
}
|
||||
|
||||
// Check if request has thinking config
|
||||
export function hasThinkingConfig(body) {
|
||||
return !!(body.reasoning_effort || body.thinking?.type === "enabled");
|
||||
}
|
||||
|
||||
// Normalize thinking config based on last message role
|
||||
// - If lastMessage is not user → remove thinking config
|
||||
// - If lastMessage is user AND has thinking config → keep it (force enable)
|
||||
export function normalizeThinkingConfig(body) {
|
||||
if (!isLastMessageFromUser(body)) {
|
||||
delete body.reasoning_effort;
|
||||
delete body.thinking;
|
||||
}
|
||||
return body;
|
||||
}
|
||||
396
open-sse/services/rateLimitManager.ts
Normal file
396
open-sse/services/rateLimitManager.ts
Normal file
@@ -0,0 +1,396 @@
|
||||
/**
|
||||
* Rate Limit Manager — Adaptive rate limiting using Bottleneck
|
||||
*
|
||||
* Creates per-provider+connection limiters that auto-learn rate limits
|
||||
* from API response headers (x-ratelimit-*, retry-after, anthropic-ratelimit-*).
|
||||
*
|
||||
* Default: ENABLED for API key providers (safety net), DISABLED for OAuth.
|
||||
* Can be toggled per provider connection via dashboard.
|
||||
*/
|
||||
|
||||
import Bottleneck from "bottleneck";
|
||||
import { parseRetryAfterFromBody, lockModel } from "./accountFallback.ts";
|
||||
import { getProviderCategory } from "../config/providerRegistry.ts";
|
||||
import { DEFAULT_API_LIMITS } from "../config/constants.ts";
|
||||
|
||||
// Store limiters keyed by "provider:connectionId" (and optionally ":model")
|
||||
const limiters = new Map();
|
||||
|
||||
// Store connections that have rate limit protection enabled
|
||||
const enabledConnections = new Set();
|
||||
|
||||
// Track initialization
|
||||
let initialized = false;
|
||||
|
||||
// Default conservative settings (before we learn from headers)
|
||||
const DEFAULT_SETTINGS = {
|
||||
maxConcurrent: 10,
|
||||
minTime: 0, // No throttle by default — let headers teach us
|
||||
reservoir: null, // No initial reservoir — unlimited until we learn
|
||||
reservoirRefreshAmount: null,
|
||||
reservoirRefreshInterval: null,
|
||||
};
|
||||
|
||||
/**
|
||||
* Initialize rate limit protection from persisted connection settings.
|
||||
* Called once on app startup.
|
||||
*/
|
||||
export async function initializeRateLimits() {
|
||||
if (initialized) return;
|
||||
initialized = true;
|
||||
|
||||
try {
|
||||
const { getProviderConnections } = await import("@/lib/localDb");
|
||||
const connections = await getProviderConnections();
|
||||
let explicitCount = 0;
|
||||
let autoCount = 0;
|
||||
|
||||
for (const conn of connections) {
|
||||
if (conn.rateLimitProtection) {
|
||||
// Explicitly enabled by user
|
||||
enabledConnections.add(conn.id);
|
||||
explicitCount++;
|
||||
} else if (
|
||||
conn.provider &&
|
||||
getProviderCategory(conn.provider) === "apikey" &&
|
||||
conn.isActive
|
||||
) {
|
||||
// Auto-enable for API key providers (safety net)
|
||||
enabledConnections.add(conn.id);
|
||||
autoCount++;
|
||||
|
||||
// Create a pre-configured limiter with conservative defaults
|
||||
const key = `${conn.provider}:${conn.id}`;
|
||||
if (!limiters.has(key)) {
|
||||
limiters.set(
|
||||
key,
|
||||
new Bottleneck({
|
||||
maxConcurrent: DEFAULT_API_LIMITS.concurrentRequests,
|
||||
minTime: DEFAULT_API_LIMITS.minTimeBetweenRequests,
|
||||
reservoir: DEFAULT_API_LIMITS.requestsPerMinute,
|
||||
reservoirRefreshAmount: DEFAULT_API_LIMITS.requestsPerMinute,
|
||||
reservoirRefreshInterval: 60 * 1000, // Refresh every minute
|
||||
id: key,
|
||||
})
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if (explicitCount > 0 || autoCount > 0) {
|
||||
console.log(
|
||||
`🛡️ [RATE-LIMIT] Loaded ${explicitCount} explicit + ${autoCount} auto-enabled (API key) protection(s)`
|
||||
);
|
||||
}
|
||||
} catch (err) {
|
||||
console.error("[RATE-LIMIT] Failed to load settings:", err.message);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Enable rate limit protection for a connection
|
||||
*/
|
||||
export function enableRateLimitProtection(connectionId) {
|
||||
enabledConnections.add(connectionId);
|
||||
}
|
||||
|
||||
/**
|
||||
* Disable rate limit protection for a connection
|
||||
*/
|
||||
export function disableRateLimitProtection(connectionId) {
|
||||
enabledConnections.delete(connectionId);
|
||||
// Clean up limiters for this connection
|
||||
for (const [key] of limiters) {
|
||||
if (key.includes(connectionId)) {
|
||||
const limiter = limiters.get(key);
|
||||
limiter?.disconnect();
|
||||
limiters.delete(key);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if rate limit protection is enabled for a connection
|
||||
*/
|
||||
export function isRateLimitEnabled(connectionId) {
|
||||
return enabledConnections.has(connectionId);
|
||||
}
|
||||
|
||||
/**
|
||||
* Get or create a limiter for a given provider+connection combination
|
||||
*/
|
||||
function getLimiter(provider, connectionId, model = null) {
|
||||
const key = model ? `${provider}:${connectionId}:${model}` : `${provider}:${connectionId}`;
|
||||
|
||||
if (!limiters.has(key)) {
|
||||
const limiter = new Bottleneck({
|
||||
...DEFAULT_SETTINGS,
|
||||
id: key,
|
||||
});
|
||||
|
||||
// Log when jobs are queued
|
||||
limiter.on("queued", () => {
|
||||
const counts = limiter.counts();
|
||||
if (counts.QUEUED > 0) {
|
||||
console.log(
|
||||
`⏳ [RATE-LIMIT] ${key} — ${counts.QUEUED} request(s) queued, ${counts.RUNNING} running`
|
||||
);
|
||||
}
|
||||
});
|
||||
|
||||
limiters.set(key, limiter);
|
||||
}
|
||||
|
||||
return limiters.get(key);
|
||||
}
|
||||
|
||||
/**
|
||||
* Acquire a rate limit slot before making a request.
|
||||
* If rate limiting is disabled for this connection, returns immediately.
|
||||
*
|
||||
* @param {string} provider - Provider ID
|
||||
* @param {string} connectionId - Connection ID
|
||||
* @param {string} model - Model name (optional, for per-model limits)
|
||||
* @param {Function} fn - The async function to execute (e.g., executor.execute)
|
||||
* @returns {Promise<any>} Result of fn()
|
||||
*/
|
||||
export async function withRateLimit(provider, connectionId, model, fn) {
|
||||
if (!enabledConnections.has(connectionId)) {
|
||||
return fn();
|
||||
}
|
||||
|
||||
const limiter = getLimiter(provider, connectionId, null);
|
||||
return limiter.schedule(fn);
|
||||
}
|
||||
|
||||
// ─── Header Parsing ──────────────────────────────────────────────────────────
|
||||
|
||||
/**
|
||||
* Standard headers used by most providers (OpenAI, Fireworks, etc.)
|
||||
*/
|
||||
const STANDARD_HEADERS = {
|
||||
limit: "x-ratelimit-limit-requests",
|
||||
remaining: "x-ratelimit-remaining-requests",
|
||||
reset: "x-ratelimit-reset-requests",
|
||||
limitTokens: "x-ratelimit-limit-tokens",
|
||||
remainingTokens: "x-ratelimit-remaining-tokens",
|
||||
resetTokens: "x-ratelimit-reset-tokens",
|
||||
retryAfter: "retry-after",
|
||||
overLimit: "x-ratelimit-over-limit",
|
||||
};
|
||||
|
||||
/**
|
||||
* Anthropic uses custom headers
|
||||
*/
|
||||
const ANTHROPIC_HEADERS = {
|
||||
limit: "anthropic-ratelimit-requests-limit",
|
||||
remaining: "anthropic-ratelimit-requests-remaining",
|
||||
reset: "anthropic-ratelimit-requests-reset",
|
||||
limitTokens: "anthropic-ratelimit-input-tokens-limit",
|
||||
remainingTokens: "anthropic-ratelimit-input-tokens-remaining",
|
||||
resetTokens: "anthropic-ratelimit-input-tokens-reset",
|
||||
retryAfter: "retry-after",
|
||||
};
|
||||
|
||||
/**
|
||||
* Parse a reset time string into milliseconds.
|
||||
* Formats: "1s", "1m", "1h", "1ms", "60", ISO date, Unix timestamp
|
||||
*/
|
||||
function parseResetTime(value) {
|
||||
if (!value) return null;
|
||||
|
||||
// Duration strings: "1s", "500ms", "1m30s"
|
||||
const durationMatch = value.match(/^(?:(\d+)h)?(?:(\d+)m(?!s))?(?:(\d+)s)?(?:(\d+)ms)?$/);
|
||||
if (durationMatch) {
|
||||
const [, h, m, s, ms] = durationMatch;
|
||||
return (
|
||||
(parseInt(h || 0) * 3600 + parseInt(m || 0) * 60 + parseInt(s || 0)) * 1000 +
|
||||
parseInt(ms || 0)
|
||||
);
|
||||
}
|
||||
|
||||
// Pure number: assume seconds
|
||||
const num = parseFloat(value);
|
||||
if (!isNaN(num) && num > 0) {
|
||||
// If it looks like a Unix timestamp (> year 2025)
|
||||
if (num > 1700000000) {
|
||||
return Math.max(0, num * 1000 - Date.now());
|
||||
}
|
||||
return num * 1000;
|
||||
}
|
||||
|
||||
// ISO date string
|
||||
try {
|
||||
const date = new Date(value);
|
||||
if (!isNaN(date.getTime())) {
|
||||
return Math.max(0, date.getTime() - Date.now());
|
||||
}
|
||||
} catch {}
|
||||
|
||||
return null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Update rate limiter based on API response headers.
|
||||
* Called after every successful or failed response from a provider.
|
||||
*
|
||||
* @param {string} provider - Provider ID
|
||||
* @param {string} connectionId - Connection ID
|
||||
* @param {Headers} headers - Response headers
|
||||
* @param {number} status - HTTP status code
|
||||
* @param {string} model - Model name
|
||||
*/
|
||||
export function updateFromHeaders(provider, connectionId, headers, status, model = null) {
|
||||
if (!enabledConnections.has(connectionId)) return;
|
||||
if (!headers) return;
|
||||
|
||||
const limiter = getLimiter(provider, connectionId, null);
|
||||
const headerMap =
|
||||
provider === "claude" || provider === "anthropic" ? ANTHROPIC_HEADERS : STANDARD_HEADERS;
|
||||
|
||||
// Get header values (handle both Headers object and plain object)
|
||||
const getHeader = (name) => {
|
||||
if (typeof headers.get === "function") return headers.get(name);
|
||||
return headers[name] || null;
|
||||
};
|
||||
|
||||
const limit = parseInt(getHeader(headerMap.limit));
|
||||
const remaining = parseInt(getHeader(headerMap.remaining));
|
||||
const resetStr = getHeader(headerMap.reset);
|
||||
const retryAfterStr = getHeader(headerMap.retryAfter);
|
||||
const overLimit = getHeader(STANDARD_HEADERS.overLimit);
|
||||
|
||||
// Handle 429 — rate limited
|
||||
if (status === 429) {
|
||||
const retryAfterMs = parseResetTime(retryAfterStr) || 60000; // Default 60s
|
||||
console.log(
|
||||
`🚫 [RATE-LIMIT] ${provider}:${connectionId.slice(0, 8)} — 429 received, pausing for ${Math.ceil(retryAfterMs / 1000)}s`
|
||||
);
|
||||
|
||||
limiter.updateSettings({
|
||||
reservoir: 0,
|
||||
reservoirRefreshAmount: limit || 60,
|
||||
reservoirRefreshInterval: retryAfterMs,
|
||||
});
|
||||
return;
|
||||
}
|
||||
|
||||
// Handle "over limit" soft warning (Fireworks)
|
||||
if (overLimit === "yes") {
|
||||
console.log(
|
||||
`⚠️ [RATE-LIMIT] ${provider}:${connectionId.slice(0, 8)} — near capacity, slowing down`
|
||||
);
|
||||
limiter.updateSettings({
|
||||
minTime: 200, // Add 200ms between requests
|
||||
});
|
||||
return;
|
||||
}
|
||||
|
||||
// Normal response — update limiter from headers
|
||||
if (!isNaN(limit) && limit > 0) {
|
||||
const resetMs = parseResetTime(resetStr) || 60000;
|
||||
|
||||
// Calculate optimal minTime from RPM limit
|
||||
const minTime = Math.max(0, Math.floor(60000 / limit) - 10); // Small buffer
|
||||
|
||||
const updates: Record<string, any> = { minTime };
|
||||
|
||||
// If remaining is low (< 10% of limit), set reservoir to throttle immediately
|
||||
if (!isNaN(remaining)) {
|
||||
if (remaining < limit * 0.1) {
|
||||
updates.reservoir = remaining;
|
||||
updates.reservoirRefreshAmount = limit;
|
||||
updates.reservoirRefreshInterval = resetMs;
|
||||
console.log(
|
||||
`⚠️ [RATE-LIMIT] ${provider}:${connectionId.slice(0, 8)} — ${remaining}/${limit} remaining, throttling`
|
||||
);
|
||||
} else if (remaining > limit * 0.5) {
|
||||
// Plenty of headroom — relax the limiter
|
||||
updates.minTime = 0;
|
||||
updates.reservoir = null;
|
||||
updates.reservoirRefreshAmount = null;
|
||||
updates.reservoirRefreshInterval = null;
|
||||
}
|
||||
}
|
||||
|
||||
limiter.updateSettings(updates);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Get current rate limit status for a provider+connection (for dashboard display)
|
||||
*/
|
||||
export function getRateLimitStatus(provider, connectionId) {
|
||||
const key = `${provider}:${connectionId}`;
|
||||
const limiter = limiters.get(key);
|
||||
|
||||
if (!limiter) {
|
||||
return {
|
||||
enabled: enabledConnections.has(connectionId),
|
||||
active: false,
|
||||
queued: 0,
|
||||
running: 0,
|
||||
};
|
||||
}
|
||||
|
||||
const counts = limiter.counts();
|
||||
return {
|
||||
enabled: enabledConnections.has(connectionId),
|
||||
active: true,
|
||||
queued: counts.QUEUED || 0,
|
||||
running: counts.RUNNING || 0,
|
||||
executing: counts.EXECUTING || 0,
|
||||
done: counts.DONE || 0,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Get all active limiters status (for dashboard overview)
|
||||
*/
|
||||
export function getAllRateLimitStatus() {
|
||||
const result: Record<string, any> = {};
|
||||
for (const [key, limiter] of limiters) {
|
||||
const counts = limiter.counts();
|
||||
result[key] = {
|
||||
queued: counts.QUEUED || 0,
|
||||
running: counts.RUNNING || 0,
|
||||
executing: counts.EXECUTING || 0,
|
||||
};
|
||||
}
|
||||
return result;
|
||||
}
|
||||
|
||||
/**
|
||||
* Update rate limiter based on API response body (JSON error responses).
|
||||
* Providers embed retry info in JSON payloads in different formats.
|
||||
* Should be called alongside updateFromHeaders for 4xx/5xx responses.
|
||||
*
|
||||
* @param {string} provider - Provider ID
|
||||
* @param {string} connectionId - Connection ID
|
||||
* @param {string|object} responseBody - Response body (string or parsed JSON)
|
||||
* @param {number} status - HTTP status code
|
||||
* @param {string} model - Model name (for per-model lockouts)
|
||||
*/
|
||||
export function updateFromResponseBody(provider, connectionId, responseBody, status, model = null) {
|
||||
if (!enabledConnections.has(connectionId)) return;
|
||||
|
||||
const { retryAfterMs, reason } = parseRetryAfterFromBody(responseBody);
|
||||
|
||||
if (retryAfterMs && retryAfterMs > 0) {
|
||||
const limiter = getLimiter(provider, connectionId, null);
|
||||
console.log(
|
||||
`🚫 [RATE-LIMIT] ${provider}:${connectionId.slice(0, 8)} — body-parsed retry: ${Math.ceil(retryAfterMs / 1000)}s (${reason})`
|
||||
);
|
||||
|
||||
limiter.updateSettings({
|
||||
reservoir: 0,
|
||||
reservoirRefreshAmount: 60,
|
||||
reservoirRefreshInterval: retryAfterMs,
|
||||
});
|
||||
|
||||
// Also apply model-level lockout if model is known
|
||||
if (model) {
|
||||
lockModel(provider, connectionId, model, reason, retryAfterMs);
|
||||
}
|
||||
}
|
||||
}
|
||||
179
open-sse/services/rateLimitSemaphore.ts
Normal file
179
open-sse/services/rateLimitSemaphore.ts
Normal file
@@ -0,0 +1,179 @@
|
||||
/**
|
||||
* Rate-Limit Semaphore
|
||||
*
|
||||
* Per-model concurrency limiter with FIFO queue for round-robin combo strategy.
|
||||
* When a model is at max concurrency, requests wait in a queue instead of failing.
|
||||
* When a model hits rate-limits, it's temporarily paused and queued requests wait.
|
||||
*
|
||||
* All state is in-memory — resets on server restart (by design, since rate-limit
|
||||
* windows are typically short-lived).
|
||||
*/
|
||||
|
||||
/**
|
||||
* @typedef {Object} ModelGate
|
||||
* @property {number} running - Currently running requests
|
||||
* @property {number} max - Max concurrent requests
|
||||
* @property {Array<{resolve: Function, reject: Function, timer: NodeJS.Timeout}>} queue - FIFO wait queue
|
||||
* @property {number|null} rateLimitedUntil - Timestamp when rate-limit expires (null = not limited)
|
||||
*/
|
||||
|
||||
/** @type {Map<string, ModelGate>} */
|
||||
const gates = new Map();
|
||||
|
||||
/**
|
||||
* Get or create gate for a model
|
||||
* @param {string} modelStr
|
||||
* @param {number} maxConcurrency
|
||||
* @returns {ModelGate}
|
||||
*/
|
||||
function getGate(modelStr, maxConcurrency = 3) {
|
||||
if (!gates.has(modelStr)) {
|
||||
gates.set(modelStr, {
|
||||
running: 0,
|
||||
max: maxConcurrency,
|
||||
queue: [],
|
||||
rateLimitedUntil: null,
|
||||
});
|
||||
}
|
||||
const gate = gates.get(modelStr);
|
||||
// Update max if config changed
|
||||
gate.max = maxConcurrency;
|
||||
return gate;
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if a model is currently rate-limited
|
||||
* @param {ModelGate} gate
|
||||
* @returns {boolean}
|
||||
*/
|
||||
function isRateLimited(gate) {
|
||||
if (!gate.rateLimitedUntil) return false;
|
||||
if (Date.now() >= gate.rateLimitedUntil) {
|
||||
gate.rateLimitedUntil = null;
|
||||
return false;
|
||||
}
|
||||
return true;
|
||||
}
|
||||
|
||||
/**
|
||||
* Try to drain queued requests when slots become available
|
||||
* @param {string} modelStr
|
||||
*/
|
||||
function drainQueue(modelStr) {
|
||||
const gate = gates.get(modelStr);
|
||||
if (!gate) return;
|
||||
|
||||
while (gate.queue.length > 0 && gate.running < gate.max && !isRateLimited(gate)) {
|
||||
const next = gate.queue.shift();
|
||||
clearTimeout(next.timer);
|
||||
gate.running++;
|
||||
next.resolve(createReleaseFn(modelStr));
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a release function for a slot
|
||||
* @param {string} modelStr
|
||||
* @returns {Function}
|
||||
*/
|
||||
function createReleaseFn(modelStr) {
|
||||
let released = false;
|
||||
return () => {
|
||||
if (released) return;
|
||||
released = true;
|
||||
const gate = gates.get(modelStr);
|
||||
if (gate && gate.running > 0) {
|
||||
gate.running--;
|
||||
drainQueue(modelStr);
|
||||
}
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Acquire a concurrency slot for a model.
|
||||
* If slots are available and model is not rate-limited, resolves immediately.
|
||||
* Otherwise waits in a FIFO queue until a slot opens or timeout expires.
|
||||
*
|
||||
* @param {string} modelStr - The model identifier
|
||||
* @param {Object} [options]
|
||||
* @param {number} [options.maxConcurrency=3] - Max concurrent requests for this model
|
||||
* @param {number} [options.timeoutMs=30000] - Max wait time in queue
|
||||
* @returns {Promise<Function>} Release function — MUST be called when done
|
||||
* @throws {Error} If queue timeout expires ("SEMAPHORE_TIMEOUT")
|
||||
*/
|
||||
export function acquire(modelStr, { maxConcurrency = 3, timeoutMs = 30000 } = {}) {
|
||||
const gate = getGate(modelStr, maxConcurrency);
|
||||
|
||||
// Fast path: slot available and not rate-limited
|
||||
if (gate.running < gate.max && !isRateLimited(gate)) {
|
||||
gate.running++;
|
||||
return Promise.resolve(createReleaseFn(modelStr));
|
||||
}
|
||||
|
||||
// Slow path: enqueue and wait
|
||||
return new Promise((resolve, reject) => {
|
||||
const timer = setTimeout(() => {
|
||||
// Remove from queue on timeout
|
||||
const idx = gate.queue.findIndex((item) => item.timer === timer);
|
||||
if (idx !== -1) gate.queue.splice(idx, 1);
|
||||
const err = new Error(`Semaphore timeout after ${timeoutMs}ms for ${modelStr}`);
|
||||
(err as any).code = "SEMAPHORE_TIMEOUT";
|
||||
reject(err);
|
||||
}, timeoutMs);
|
||||
|
||||
gate.queue.push({ resolve, reject, timer });
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Mark a model as rate-limited for a given duration.
|
||||
* Existing running requests continue, but new acquisitions are blocked
|
||||
* until the cooldown expires. After expiry, the queue drains automatically.
|
||||
*
|
||||
* @param {string} modelStr - The model identifier
|
||||
* @param {number} cooldownMs - How long to block (milliseconds)
|
||||
*/
|
||||
export function markRateLimited(modelStr, cooldownMs) {
|
||||
const gate = getGate(modelStr);
|
||||
gate.rateLimitedUntil = Date.now() + cooldownMs;
|
||||
|
||||
// Schedule drain after cooldown expires
|
||||
setTimeout(() => {
|
||||
if (gate.rateLimitedUntil && Date.now() >= gate.rateLimitedUntil) {
|
||||
gate.rateLimitedUntil = null;
|
||||
drainQueue(modelStr);
|
||||
}
|
||||
}, cooldownMs + 50); // +50ms buffer
|
||||
}
|
||||
|
||||
/**
|
||||
* Get stats for all tracked models (for monitoring/UI)
|
||||
* @returns {Object} Map of modelStr → { running, queued, max, rateLimitedUntil }
|
||||
*/
|
||||
export function getStats() {
|
||||
const stats = {};
|
||||
for (const [model, gate] of gates) {
|
||||
stats[model] = {
|
||||
running: gate.running,
|
||||
queued: gate.queue.length,
|
||||
max: gate.max,
|
||||
rateLimitedUntil: gate.rateLimitedUntil
|
||||
? new Date(gate.rateLimitedUntil).toISOString()
|
||||
: null,
|
||||
};
|
||||
}
|
||||
return stats;
|
||||
}
|
||||
|
||||
/**
|
||||
* Reset all gates (for testing)
|
||||
*/
|
||||
export function resetAll() {
|
||||
for (const [, gate] of gates) {
|
||||
for (const item of gate.queue) {
|
||||
clearTimeout(item.timer);
|
||||
item.reject(new Error("Semaphore reset"));
|
||||
}
|
||||
}
|
||||
gates.clear();
|
||||
}
|
||||
179
open-sse/services/sessionManager.ts
Normal file
179
open-sse/services/sessionManager.ts
Normal file
@@ -0,0 +1,179 @@
|
||||
/**
|
||||
* Session Fingerprinting — Phase 5
|
||||
*
|
||||
* Generates stable session IDs for sticky routing,
|
||||
* prompt caching, and per-session tracking.
|
||||
*/
|
||||
|
||||
import { createHash } from "node:crypto";
|
||||
|
||||
// In-memory session store with metadata
|
||||
// key: sessionId → { createdAt, lastActive, requestCount, connectionId? }
|
||||
const sessions = new Map();
|
||||
|
||||
// Auto-cleanup sessions older than 30 minutes
|
||||
const SESSION_TTL_MS = 30 * 60 * 1000;
|
||||
const _cleanupTimer = setInterval(() => {
|
||||
const now = Date.now();
|
||||
for (const [key, entry] of sessions) {
|
||||
if (now - entry.lastActive > SESSION_TTL_MS) sessions.delete(key);
|
||||
}
|
||||
}, 60_000);
|
||||
_cleanupTimer.unref();
|
||||
|
||||
/**
|
||||
* Generate a stable session fingerprint from request characteristics.
|
||||
* Same client + same conversation → same session ID.
|
||||
*
|
||||
* Fingerprint factors:
|
||||
* - System prompt hash (stable per conversation/tool)
|
||||
* - First user message hash (stable per conversation)
|
||||
* - Model name
|
||||
* - Provider (optional)
|
||||
* - Tools signature (sorted tool names)
|
||||
*
|
||||
* @param {object} body - Request body
|
||||
* @param {object} [options] - Extra context
|
||||
* @returns {string} Session ID (hex hash)
|
||||
*/
|
||||
export function generateSessionId(body, options: any = {}) {
|
||||
const parts = [];
|
||||
|
||||
// Model contributes to fingerprint
|
||||
if (body.model) parts.push(`model:${body.model}`);
|
||||
|
||||
// Provider binding
|
||||
if (options.provider) parts.push(`provider:${options.provider}`);
|
||||
|
||||
// System prompt hash (first 32 chars of system content)
|
||||
const systemPrompt = extractSystemPrompt(body);
|
||||
if (systemPrompt) {
|
||||
parts.push(`sys:${hashShort(systemPrompt)}`);
|
||||
}
|
||||
|
||||
// First user message hash (identifies the conversation)
|
||||
const firstUser = extractFirstUserMessage(body);
|
||||
if (firstUser) {
|
||||
parts.push(`user0:${hashShort(firstUser)}`);
|
||||
}
|
||||
|
||||
// Tools signature (sorted names)
|
||||
if (body.tools && Array.isArray(body.tools) && body.tools.length > 0) {
|
||||
const toolNames = body.tools
|
||||
.map((t) => t.name || t.function?.name || "")
|
||||
.filter(Boolean)
|
||||
.sort()
|
||||
.join(",");
|
||||
if (toolNames) parts.push(`tools:${hashShort(toolNames)}`);
|
||||
}
|
||||
|
||||
// Connection ID for sticky routing
|
||||
if (options.connectionId) parts.push(`conn:${options.connectionId}`);
|
||||
|
||||
if (parts.length === 0) return null;
|
||||
|
||||
const fingerprint = parts.join("|");
|
||||
return createHash("sha256").update(fingerprint).digest("hex").slice(0, 16);
|
||||
}
|
||||
|
||||
/**
|
||||
* Touch or create a session
|
||||
*/
|
||||
export function touchSession(sessionId, connectionId = null) {
|
||||
if (!sessionId) return;
|
||||
const existing = sessions.get(sessionId);
|
||||
if (existing) {
|
||||
existing.lastActive = Date.now();
|
||||
existing.requestCount++;
|
||||
if (connectionId) existing.connectionId = connectionId;
|
||||
} else {
|
||||
sessions.set(sessionId, {
|
||||
createdAt: Date.now(),
|
||||
lastActive: Date.now(),
|
||||
requestCount: 1,
|
||||
connectionId,
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Get session info (for sticky routing decisions)
|
||||
*/
|
||||
export function getSessionInfo(sessionId) {
|
||||
if (!sessionId) return null;
|
||||
const entry = sessions.get(sessionId);
|
||||
if (!entry) return null;
|
||||
if (Date.now() - entry.lastActive > SESSION_TTL_MS) {
|
||||
sessions.delete(sessionId);
|
||||
return null;
|
||||
}
|
||||
return { ...entry };
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the bound connection for a session (sticky routing)
|
||||
*/
|
||||
export function getSessionConnection(sessionId) {
|
||||
const info = getSessionInfo(sessionId);
|
||||
return info?.connectionId || null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get session count (for dashboard)
|
||||
*/
|
||||
export function getActiveSessionCount() {
|
||||
return sessions.size;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get all active sessions (for dashboard)
|
||||
*/
|
||||
export function getActiveSessions() {
|
||||
const now = Date.now();
|
||||
const result = [];
|
||||
for (const [id, entry] of sessions) {
|
||||
if (now - entry.lastActive <= SESSION_TTL_MS) {
|
||||
result.push({ sessionId: id, ...entry, ageMs: now - entry.createdAt });
|
||||
}
|
||||
}
|
||||
return result;
|
||||
}
|
||||
|
||||
/**
|
||||
* Clear all sessions (for testing)
|
||||
*/
|
||||
export function clearSessions() {
|
||||
sessions.clear();
|
||||
}
|
||||
|
||||
// ─── Internal Helpers ───────────────────────────────────────────────────────
|
||||
|
||||
function hashShort(text) {
|
||||
return createHash("sha256").update(text).digest("hex").slice(0, 8);
|
||||
}
|
||||
|
||||
function extractSystemPrompt(body) {
|
||||
// Claude format: body.system
|
||||
if (body.system) {
|
||||
return typeof body.system === "string" ? body.system : JSON.stringify(body.system);
|
||||
}
|
||||
// OpenAI format: messages[0].role === "system"
|
||||
if (body.messages && Array.isArray(body.messages)) {
|
||||
const sys = body.messages.find((m) => m.role === "system" || m.role === "developer");
|
||||
if (sys) {
|
||||
return typeof sys.content === "string" ? sys.content : JSON.stringify(sys.content);
|
||||
}
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
function extractFirstUserMessage(body) {
|
||||
const messages = body.messages || body.input || [];
|
||||
if (!Array.isArray(messages)) return null;
|
||||
for (const msg of messages) {
|
||||
if (msg.role === "user") {
|
||||
return typeof msg.content === "string" ? msg.content : JSON.stringify(msg.content);
|
||||
}
|
||||
}
|
||||
return null;
|
||||
}
|
||||
171
open-sse/services/signatureCache.ts
Normal file
171
open-sse/services/signatureCache.ts
Normal file
@@ -0,0 +1,171 @@
|
||||
/**
|
||||
* Signature Cache — Phase 3
|
||||
*
|
||||
* Dynamic 3-layer cache for thinking signatures (tool, model family, session).
|
||||
* Replaces hardcoded thinking signature patterns with adaptive detection.
|
||||
*/
|
||||
|
||||
// 3-layer cache: tool → model family → session
|
||||
// Each layer stores patterns detected from responses
|
||||
const layers = {
|
||||
tool: new Map(), // e.g. "cursor" → Set of signature patterns
|
||||
family: new Map(), // e.g. "claude-sonnet" → Set of signature patterns
|
||||
session: new Map(), // e.g. sessionId → Set of signature patterns
|
||||
};
|
||||
|
||||
// Known default signatures (bootstrap — will be supplemented by learning)
|
||||
const DEFAULT_SIGNATURES = [
|
||||
"<antThinking>",
|
||||
"</antThinking>",
|
||||
"<thinking>",
|
||||
"</thinking>",
|
||||
"<internal_thought>",
|
||||
"</internal_thought>",
|
||||
];
|
||||
|
||||
// Max entries per cache layer to prevent unbounded growth
|
||||
const MAX_ENTRIES_PER_LAYER = 500;
|
||||
const MAX_PATTERNS_PER_KEY = 50;
|
||||
|
||||
/**
|
||||
* Get all matching signatures for a given context.
|
||||
* Checks all 3 layers and merges results with defaults.
|
||||
*
|
||||
* @param {object} context - { tool?, modelFamily?, sessionId? }
|
||||
* @returns {string[]} Array of unique signature patterns
|
||||
*/
|
||||
export function getSignatures(context: any = {}) {
|
||||
const patterns = new Set(DEFAULT_SIGNATURES);
|
||||
|
||||
// Layer 1: Tool (e.g., "cursor", "cline", "antigravity")
|
||||
if (context.tool && layers.tool.has(context.tool)) {
|
||||
for (const p of layers.tool.get(context.tool)) patterns.add(p);
|
||||
}
|
||||
|
||||
// Layer 2: Model family (e.g., "claude-sonnet", "claude-opus")
|
||||
if (context.modelFamily && layers.family.has(context.modelFamily)) {
|
||||
for (const p of layers.family.get(context.modelFamily)) patterns.add(p);
|
||||
}
|
||||
|
||||
// Layer 3: Session-specific
|
||||
if (context.sessionId && layers.session.has(context.sessionId)) {
|
||||
for (const p of layers.session.get(context.sessionId)) patterns.add(p);
|
||||
}
|
||||
|
||||
return Array.from(patterns);
|
||||
}
|
||||
|
||||
/**
|
||||
* Add a discovered signature pattern to the cache.
|
||||
*
|
||||
* @param {string} pattern - The signature pattern (e.g., "<antThinking>")
|
||||
* @param {object} context - { tool?, modelFamily?, sessionId? }
|
||||
*/
|
||||
export function addSignature(pattern: any, context: any = {}) {
|
||||
if (!pattern || typeof pattern !== "string") return;
|
||||
|
||||
const addToLayer = (layer, key) => {
|
||||
if (!key) return;
|
||||
if (!layer.has(key)) {
|
||||
if (layer.size >= MAX_ENTRIES_PER_LAYER) {
|
||||
// Evict oldest entry
|
||||
const firstKey = layer.keys().next().value;
|
||||
layer.delete(firstKey);
|
||||
}
|
||||
layer.set(key, new Set());
|
||||
}
|
||||
const set = layer.get(key);
|
||||
if (set.size < MAX_PATTERNS_PER_KEY) {
|
||||
set.add(pattern);
|
||||
}
|
||||
};
|
||||
|
||||
addToLayer(layers.tool, context.tool);
|
||||
addToLayer(layers.family, context.modelFamily);
|
||||
addToLayer(layers.session, context.sessionId);
|
||||
}
|
||||
|
||||
/**
|
||||
* Detect signatures in a text chunk from streaming response.
|
||||
* Auto-learns new patterns and adds them to cache.
|
||||
*
|
||||
* @param {string} text - Streaming text to scan
|
||||
* @param {object} context - { tool?, modelFamily?, sessionId? }
|
||||
* @returns {{ found: string[], cleaned: string }} Detected tags and cleaned text
|
||||
*/
|
||||
export function detectAndLearn(text: any, context: any = {}) {
|
||||
if (!text || typeof text !== "string") return { found: [], cleaned: text };
|
||||
|
||||
const found = [];
|
||||
let cleaned = text;
|
||||
|
||||
// Check all known signatures
|
||||
const known = getSignatures(context);
|
||||
for (const sig of known) {
|
||||
if (cleaned.includes(sig)) {
|
||||
found.push(sig);
|
||||
cleaned = cleaned.split(sig).join("");
|
||||
}
|
||||
}
|
||||
|
||||
// Auto-detect new XML-like thinking tags
|
||||
const tagRegex = /<\/?([a-zA-Z_][a-zA-Z0-9_]*(?:Thinking|thinking|thought|Thought|internal_thought))>/g;
|
||||
let match;
|
||||
while ((match = tagRegex.exec(text)) !== null) {
|
||||
const tag = match[0];
|
||||
if (!known.includes(tag)) {
|
||||
found.push(tag);
|
||||
addSignature(tag, context);
|
||||
cleaned = cleaned.split(tag).join("");
|
||||
}
|
||||
}
|
||||
|
||||
return { found, cleaned: cleaned.trim() || cleaned };
|
||||
}
|
||||
|
||||
/**
|
||||
* Extract model family from model name
|
||||
* "claude-sonnet-4-20250514" → "claude-sonnet"
|
||||
* "gpt-4o-2024-08-06" → "gpt-4o"
|
||||
*/
|
||||
export function getModelFamily(model) {
|
||||
if (!model) return null;
|
||||
// Remove date suffixes and version numbers
|
||||
const cleaned = model
|
||||
.replace(/-\d{4}-\d{2}-\d{2}$/, "") // Remove YYYY-MM-DD suffix
|
||||
.replace(/-\d{8,}$/, "") // Remove YYYYMMDD suffix
|
||||
.replace(/-\d+(\.\d+)*$/, "") // Remove version suffix like -4
|
||||
.replace(/@.*$/, ""); // Remove @latest etc.
|
||||
// Keep meaningful prefix
|
||||
return cleaned || model;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get cache stats (for dashboard)
|
||||
*/
|
||||
export function getCacheStats() {
|
||||
return {
|
||||
tool: {
|
||||
entries: layers.tool.size,
|
||||
patterns: Array.from(layers.tool.values()).reduce((sum, s) => sum + s.size, 0),
|
||||
},
|
||||
family: {
|
||||
entries: layers.family.size,
|
||||
patterns: Array.from(layers.family.values()).reduce((sum, s) => sum + s.size, 0),
|
||||
},
|
||||
session: {
|
||||
entries: layers.session.size,
|
||||
patterns: Array.from(layers.session.values()).reduce((sum, s) => sum + s.size, 0),
|
||||
},
|
||||
defaultCount: DEFAULT_SIGNATURES.length,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Clear all cache layers (for testing)
|
||||
*/
|
||||
export function clearCache() {
|
||||
layers.tool.clear();
|
||||
layers.family.clear();
|
||||
layers.session.clear();
|
||||
}
|
||||
66
open-sse/services/systemPrompt.ts
Normal file
66
open-sse/services/systemPrompt.ts
Normal file
@@ -0,0 +1,66 @@
|
||||
/**
|
||||
* System Prompt Injection — Phase 10
|
||||
*
|
||||
* Injects a global system prompt into all requests at proxy level.
|
||||
*/
|
||||
|
||||
// In-memory config
|
||||
let _config = {
|
||||
enabled: false,
|
||||
prompt: "",
|
||||
};
|
||||
|
||||
/**
|
||||
* Set system prompt config
|
||||
*/
|
||||
export function setSystemPromptConfig(config) {
|
||||
_config = { ..._config, ...config };
|
||||
}
|
||||
|
||||
/**
|
||||
* Get system prompt config
|
||||
*/
|
||||
export function getSystemPromptConfig() {
|
||||
return { ..._config };
|
||||
}
|
||||
|
||||
/**
|
||||
* Inject system prompt into request body.
|
||||
*
|
||||
* @param {object} body - Request body
|
||||
* @param {string} [promptText] - Override prompt text
|
||||
* @returns {object} Modified body
|
||||
*/
|
||||
export function injectSystemPrompt(body, promptText = null) {
|
||||
const text = promptText || _config.prompt;
|
||||
if (!text || !_config.enabled) return body;
|
||||
if (!body || typeof body !== "object") return body;
|
||||
if (body._skipSystemPrompt) return body;
|
||||
|
||||
const result = { ...body };
|
||||
|
||||
// OpenAI/Claude format (messages[])
|
||||
if (result.messages && Array.isArray(result.messages)) {
|
||||
const sysIdx = result.messages.findIndex((m) => m.role === "system" || m.role === "developer");
|
||||
result.messages = [...result.messages];
|
||||
if (sysIdx >= 0) {
|
||||
// Prepend to existing system message
|
||||
const msg = { ...result.messages[sysIdx] };
|
||||
msg.content = text + "\n\n" + (msg.content || "");
|
||||
result.messages[sysIdx] = msg;
|
||||
} else {
|
||||
result.messages = [{ role: "system", content: text }, ...result.messages];
|
||||
}
|
||||
}
|
||||
|
||||
// Claude format (system field)
|
||||
if (result.system !== undefined) {
|
||||
if (typeof result.system === "string") {
|
||||
result.system = text + "\n\n" + result.system;
|
||||
} else if (Array.isArray(result.system)) {
|
||||
result.system = [{ type: "text", text }, ...result.system];
|
||||
}
|
||||
}
|
||||
|
||||
return result;
|
||||
}
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user